Toast Authentication API
The Toast Authentication API implements OAuth 2.0 client credentials flow for obtaining access tokens used across all Toast platform APIs. Tokens are scoped to restaurant GUIDs and expire after a configurable period.
OpenAPI Specification
swagger: '2.0'
info:
version: 1.0.0
title: Toast authentication API
description: |
The authentication API returns an authentication token that you can present
when your integration client software uses other Toast APIs. For more
information about authentication, see [the Toast Developer
Guide](https://doc.toasttab.com/doc/devguide/authentication.html).
termsOfService: https://pos.toasttab.com/api-terms-of-use
contact:
name: Toast developer support
schemes:
- https
host: toast-api-server
basePath: /authentication/v1
consumes:
- application/json
externalDocs:
description: Authentication developer guide
url: https://doc.toasttab.com/doc/devguide/authentication.html
tags:
- name: Authentication
produces:
- application/json
definitions:
AuthenticationRequest:
type: object
description: |
Authentication credentials for your Toast API integration client software.
properties:
clientId:
description: |
The identifier string for your Toast API client. You receive the
identifier string from the Toast integrations team.
type: string
example: VKuhk4NaLedOcjZpJM8grvdrsFi3MlcM
clientSecret:
description: |
The secret string that corresponds to your Toast API client. You
receive the secret string from the Toast integrations team.
type: string
example: eS960aiKdvgbSDcLUCk68HR2CJKwwHNO2HKfgxjCWxoj27KIp6jFAi2XOOc_oCuv
userAccessType:
description: |
Always include the `userAccessType` value and set it to
`TOAST_MACHINE_CLIENT`.
type: string
example: TOAST_MACHINE_CLIENT
AuthenticationResponse:
type: object
description: |
A wrapper object for the response to a successful Toast API authentication
request.
properties:
token:
description: |
An `AuthenticationToken` object containing information about a Toast
platform API session, including an authentication token string that
your Toast API client software can present when using other Toast
platform APIs.
type: object
$ref: '#/definitions/AuthenticationToken'
status:
description: The value `SUCCESS` indicates that your authentication request was successful.
type: string
example: SUCCESS
AuthenticationToken:
type: object
description: |
Information about a Toast platform API session, including an
authentication token string that your Toast API client software can
present when using other Toast platform APIs.
properties:
tokenType:
description: |
The OAuth 2 authentication scheme used for the authentication token.
Toast API authentication uses the bearer authentication scheme.
type: string
example: Bearer
scope:
description: |
The scope value in the authentication token request response is
`null`. The `accessToken` JSON Web Token (JWT) contains the list of
[scopes for your Toast API
client](https://dev.toasttab.com/doc/devguide/apiScopes.html).
type: string
expiresIn:
description: |
The number of seconds that the authentication token is valid.
type: integer
example: 86400
accessToken:
description: |
A JSON Web Token (JWT) string that contains an authentication token.
You [present this string when you make
requests](https://dev.toasttab.com/doc/devguide/authentication.html#using-authentication-token)
to other Toast API resources. The JWT includes information about your
Toast API client.
type: string
idToken:
description: |
For internal use only.
type: string
refreshToken:
description: |
For internal use only.
type: string
ErrorMessage:
type: object
description: |
An object that contains information about one or more errors that the
Toast platform encountered when processing your API request.
properties:
status:
description: |
The HTTP status code of the response.
type: string
code:
description: |
A numeric identifier for the error condition.
type: integer
message:
description: |
A description of the error condition.
type: string
messageKey:
description: |
Reserved for future use.
type: string
fieldName:
description: |
Reserved for future use.
type: string
link:
description: |
The URL of a resource that provides more information about the error
condition.
type: string
requestId:
description: |
The unique identifier of the HTTP request that your client sent to the Toast API.
type: string
developerMessage:
description: |
Additional detail about the error condition, if it is available.
type: string
errors:
description: |
A JSON array of `ErrorMessage` objects.
type: array
items:
$ref: '#/definitions/ErrorMessage'
canRetry:
description: |
Reserved for future use.
type: string
paths:
/authentication/login:
post:
tags:
- Authentication
summary: Toast Get an Authentication Token
description: |
Returns an authentication token that your Toast API client can present
when using other Toast platform APIs.
externalDocs:
description: Authentication developer guide
url: https://doc.toasttab.com/doc/devguide/authentication.html
operationId: authenticationLoginPost
produces:
- application/json
parameters:
- name: body
description: |
The authentication credentials for your Toast API client integration
software.
in: body
required: true
schema:
$ref: '#/definitions/AuthenticationRequest'
responses:
'200':
description: |
A JSON `AuthenticationResponse` object that includes an
authentication token string.
schema:
$ref: '#/definitions/AuthenticationResponse'
'401':
description: |
The Toast API client credentials in your request are not valid.
schema:
$ref: '#/definitions/ErrorMessage'