Toast Authentication API

openapi: 3.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.'
  termsOfService: https://pos.toasttab.com/api-terms-of-use
  contact:
    name: Toast developer support
servers:
- url: https://toast-api-server/authentication/v1
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
      responses:
        '200':
          description: 'A JSON `AuthenticationResponse` object that includes an

            authentication token string.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationResponse'
        '401':
          description: 'The Toast API client credentials in your request are not valid.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRequest'
        description: 'The authentication credentials for your Toast API client integration

          software.

          '
        required: true
components:
  schemas:
    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: '#/components/schemas/AuthenticationToken'
        status:
          description: The value `SUCCESS` indicates that your authentication request was successful.
          type: string
          example: SUCCESS
    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: '#/components/schemas/ErrorMessage'
        canRetry:
          description: 'Reserved for future use.

            '
          type: string
    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
    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
externalDocs:
  description: Authentication developer guide
  url: https://doc.toasttab.com/doc/devguide/authentication.html