Tray.ai Authentication API

openapi: 3.2.0
info:
  title: Tray.ai Embedded Authentication API
  description: The Tray.ai Embedded API is a GraphQL-based API that allows partners and customers to present in-app embedded integration experiences using Tray's UI components.
  version: 1.0.0
  contact:
    name: Tray.ai Support
    url: https://tray.ai
  termsOfService: https://tray.ai/terms
  license:
    name: Proprietary
    url: https://tray.ai/terms
servers:
- url: https://tray.io
  description: US Region (Default)
- url: https://eu1.tray.io
  description: EU Region
- url: https://ap1.tray.io
  description: APAC Region
security:
- bearerAuth: []
tags:
- name: Authentication
  description: Generate and manage user tokens for authenticating API calls. The authorize mutation generates a user token from a master token.
paths:
  /graphql:
    get:
      operationId: graphqlPlayground
      summary: Tray.ai GraphQL Playground
      description: Access the GraphQL Playground interface for exploring the Tray Embedded API interactively. This is only available for development and testing purposes.
      tags:
      - Authentication
      responses:
        '200':
          description: GraphQL Playground HTML interface
          content:
            text/html:
              schema:
                type: string
  /graphql#authorize:
    post:
      operationId: authorize
      summary: Tray.ai Create User Token (Authorize)
      description: Generates a user access token from a master token for a specific user. The returned token is used as a Bearer token for user-scoped API calls such as managing solution instances and authentications. Requires a master token.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: "mutation {\n  authorize(input: {\n    userId: \"user-uuid-here\"\n  }) {\n    accessToken\n  }\n}"
      responses:
        '200':
          description: User token generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      authorize:
                        type: object
                        properties:
                          accessToken:
                            type: string
                            description: Bearer token for user-scoped API calls
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    GraphQLError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Error message
              locations:
                type: array
                items:
                  type: object
                  properties:
                    line:
                      type: integer
                    column:
                      type: integer
              path:
                type: array
                items:
                  type: string
    GraphQLRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation string
        variables:
          type: object
          description: Variables to pass to the GraphQL query or mutation
        operationName:
          type: string
          description: The name of the operation to execute if the query contains multiple operations
  responses:
    Unauthorized:
      description: Authentication failed. The bearer token is missing, invalid, or does not have sufficient permissions for the requested operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GraphQLError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use either a master token (obtained from Tray Embedded UI settings) or a user token (obtained via the authorize mutation). Master tokens are required for admin operations like managing users. User tokens are required for user-scoped operations like managing solution instances.