Toast Authentication API

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
host: toast-api-server
basePath: /authentication/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Authentication
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'
definitions:
  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. \n"
        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
  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
externalDocs:
  description: Authentication developer guide
  url: https://doc.toasttab.com/doc/devguide/authentication.html