openapi: 3.1.0
info:
  title: Tray.ai Embedded Authentication Authentications 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. It provides programmatic access to manage users, solutions, solution instances, authentications, workflows, and connector operations. All API calls are made via HTTP POST to the GraphQL endpoint with Bearer token authentication. The API supports two token types: master tokens (for admin operations like managing users) and user tokens (for user-scoped operations like managing solution instances). This is a backend-only API; client-side JavaScript calls are blocked by CORS.'
  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: Authentications
  description: Create, retrieve, and delete third-party service authentications that power Tray connectors (e.g., Salesforce, Slack).
paths:
  /graphql#createUserAuthentication:
    post:
      operationId: createUserAuthentication
      summary: Tray.ai Create User Authentication
      description: Creates a new authentication for a third-party service (e.g., Salesforce, Slack) for a specific user. Returns an authId that can be used when creating or updating solution instances. Note that OAuth-based authentications cannot be created via API unless you own the service. Requires a user token.
      tags:
      - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: "mutation {\n  createUserAuthentication(input: {\n    name: \"My Salesforce Auth\",\n    serviceId: \"service-uuid-here\",\n    serviceEnvironmentId: \"env-uuid-here\",\n    data: [{\n      key: \"api_key\",\n      value: \"your-api-key\"\n    }]\n  }) {\n    authenticationId\n  }\n}"
      responses:
        '200':
          description: Authentication created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      createUserAuthentication:
                        type: object
                        properties:
                          authenticationId:
                            type: string
                            description: The unique identifier for the created authentication
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#getAuthentications:
    post:
      operationId: getAuthentications
      summary: Tray.ai Get Authentications
      description: Retrieves a list of authentications for third-party services. Supports both master token (returns all authentications) and user token (returns user-scoped authentications).
      tags:
      - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: "query {\n  viewer {\n    authentications {\n      edges {\n        node {\n          id\n          name\n          service {\n            id\n            name\n            icon\n          }\n          serviceEnvironment {\n            id\n            title\n          }\n        }\n        cursor\n      }\n      pageInfo {\n        hasNextPage\n        endCursor\n      }\n    }\n  }\n}"
      responses:
        '200':
          description: Authentications returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      viewer:
                        type: object
                        properties:
                          authentications:
                            type: object
                            properties:
                              edges:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    node:
                                      $ref: '#/components/schemas/Authentication'
                                    cursor:
                                      type: string
                              pageInfo:
                                $ref: '#/components/schemas/PageInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /graphql#deleteAuthentication:
    post:
      operationId: deleteAuthentication
      summary: Tray.ai Delete Authentication
      description: Deletes a third-party service authentication. Requires a user token.
      tags:
      - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            example:
              query: "mutation {\n  removeAuthentication(input: {\n    authenticationId: \"auth-uuid-here\"\n  }) {\n    clientMutationId\n  }\n}"
      responses:
        '200':
          description: Authentication deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      removeAuthentication:
                        type: object
                        properties:
                          clientMutationId:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /authentications:
    get:
      operationId: listAuthentications
      summary: Tray.ai List Authentications
      description: Retrieves a list of authentications associated with the authenticated user or organization.
      tags:
      - Authentications
      responses:
        '200':
          description: Authentications returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  elements:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformAuthentication'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
    post:
      operationId: createAuthentication
      summary: Tray.ai Create Authentication
      description: Creates a new user authentication for a third-party service in Tray. Requires the serviceEnvironmentId, user data, and credentials. Returns an authentication ID that can be used with the Call Connector endpoint.
      tags:
      - Authentications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthenticationRequest'
      responses:
        '200':
          description: Authentication created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformAuthentication'
        '400':
          description: Invalid request
        '401':
          $ref: '#/components/responses/Unauthorized_2'
  /authentications/{authenticationId}:
    get:
      operationId: getAuthentication
      summary: Tray.ai Get Authentication
      description: Retrieves metadata associated with a user authentication by its ID, including auth id, serviceEnvironmentId, name, and scopes.
      tags:
      - Authentications
      parameters:
      - name: authenticationId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier for the authentication
      responses:
        '200':
          description: Authentication details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformAuthentication'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          description: Authentication not found
    delete:
      operationId: deleteAuthentication
      summary: Tray.ai Delete Authentication
      description: Deletes a user authentication using the authentication ID.
      tags:
      - Authentications
      parameters:
      - name: authenticationId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier for the authentication
      responses:
        '204':
          description: Authentication deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          description: Authentication not found
components:
  schemas:
    CreateAuthenticationRequest:
      type: object
      required:
      - name
      - serviceEnvironmentId
      properties:
        name:
          type: string
          description: Display name for the authentication
        serviceEnvironmentId:
          type: string
          description: The ID of the service environment to authenticate against
        userData:
          type: object
          description: User-specific data for the authentication
        credentials:
          type: object
          description: Credentials for the authentication (e.g., API key, OAuth tokens)
    Authentication:
      type: object
      properties:
        id:
          type: string
          description: Unique authentication identifier
        name:
          type: string
          description: Display name of the authentication
        service:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            icon:
              type: string
              format: uri
        serviceEnvironment:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
    PlatformAuthentication:
      type: object
      properties:
        id:
          type: string
          description: Unique authentication identifier
        name:
          type: string
          description: Display name of the authentication
        serviceEnvironmentId:
          type: string
          description: The service environment against which this authentication was created
        scopes:
          type: array
          items:
            type: string
          description: OAuth scopes associated with this authentication
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the authentication was created
    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
    PageInfo:
      type: object
      properties:
        hasNextPage:
          type: boolean
          description: Whether there are more results after the current page
        endCursor:
          type: string
          description: Cursor for fetching the next page
        hasPreviousPage:
          type: boolean
          description: Whether there are results before the current page
        startCursor:
          type: string
          description: Cursor for fetching the previous page
    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
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Human-readable error message
        statusCode:
          type: integer
          description: HTTP status code
  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'
    Unauthorized_2:
      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/Error'
  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.