Tray Ai Authentication

generated: '2026-09-02'
method: searched
source: >-
  https://tray.ai/documentation/developer/getting-started/prerequisites/master-and-user-tokens,
  https://tray.ai/documentation/platform/enterprise-core/organisation-management/api-users-tokens,
  https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/authentication-and-access,
  https://api.tray.io/.well-known/oauth-authorization-server,
  openapi/_original/tray-ai-platform-api-published-openapi.yaml,
  openapi/_original/tray-ai-embedded-api-published-openapi.yaml
docs: https://tray.ai/documentation/developer/getting-started/prerequisites/master-and-user-tokens
provider: Tray.ai
providerId: tray-ai
description: >-
  Tray.ai has two authentication models on one platform, and they do not overlap. The REST Platform
  API and the GraphQL Embedded API take a bearer token and have NO scope surface — authority comes
  from the token TYPE (master vs user) and from the RBAC role attached to the API user. The MCP
  server is a separate, modern OAuth 2.1 surface with dynamic client registration, PKCE S256 and
  three real scopes. A third layer sits underneath both: the per-service AUTHENTICATIONS Tray stores
  on behalf of end users, which is what a connector call actually executes under.
summary:
  types:
    - http
    - oauth2
schemes:
  - name: bearerAuth
    type: http
    scheme: bearer
    bearerFormat: JWT
    applies_to: [Tray.ai Platform API, Tray.ai Embedded API]
    description: >-
      Use either a master token (obtained from Tray Embedded UI settings / API Users & Tokens) or a
      user token (obtained via the Embedded authorize mutation). Master tokens are required for
      admin operations like managing users. User tokens are required for user-scoped operations
      like managing solution instances.
    sources:
      - openapi/_original/tray-ai-platform-api-published-openapi.yaml
      - openapi/_original/tray-ai-embedded-api-published-openapi.yaml
    scopes: none
  - name: trayMcpOAuth
    type: oauth2
    applies_to: [Tray MCP Server]
    flow: authorization_code
    pkce: S256 (required; plain not offered)
    issuer: https://auth.tray.io
    authorization_endpoint: https://auth.tray.io/server/oauth2/authorize
    token_endpoint: https://auth.tray.io/server/oauth2/token
    registration_endpoint: https://auth.tray.io/server/oauth2/register
    revocation_endpoint: https://auth.tray.io/server/oauth2/revoke
    refresh: supported
    token_endpoint_auth_methods: [client_secret_basic, none]
    scopes: [mcp:list_tools, mcp:call_tools, api:full]
    metadata: https://api.tray.io/.well-known/oauth-authorization-server
    resource_metadata: https://api.tray.io/.well-known/oauth-protected-resource/mcp
    verified: probed
    cross_ref: scopes/tray-ai-scopes.yml
token_types:
  - name: master token
    surface: [Platform API, Embedded API]
    obtained_from: Tray Embedded UI settings / Organisation management > API Users & Tokens
    acts_as: the organization
    required_for: creating end users, issuing user tokens, org-level administration
    rotation: manual
  - name: user token
    surface: [Platform API, Embedded API]
    obtained_from: 'Embedded `authorize` mutation (create-user-token), exchanged with a master token'
    acts_as: one end user
    required_for: user-scoped operations — the user's authentications and solution instances
    guidance: >-
      Mint server-side and hand only the user token to a browser. Never ship a master token to a
      front end.
  - name: RBAC API token
    surface: [Platform API, CDK CLI, Tray Sync CLI]
    obtained_from: API Users & Tokens (workspace or account scope)
    acts_as: an API user with a role
    required_for: 'tray-cdk deployments, tray-sync-cli pull/promote'
    docs: https://tray.ai/documentation/platform/enterprise-core/organisation-management/api-users-tokens
  - name: OAuth2 access token
    surface: [Tray MCP Server]
    obtained_from: https://auth.tray.io/server/oauth2/authorize
    acts_as: the signed-in Tray user, in the workspace chosen at sign-in
    required_for: tools/list and tools/call on api.tray.io/mcp
end_user_authentications:
  description: >-
    Distinct from the tokens above. An "authentication" is a stored credential for a THIRD-PARTY
    service (Salesforce, Slack, ...) that Tray holds on behalf of a user, identified by a UUID and
    passed as `authId` on every connector call.
  operations: [create-user-authentication, get-user-authentication, update-user-authentication, delete-user-authentication, get-full-authentication, get-service-environments]
  graphql_operations: [get-authentications, create-authentication, delete-authentication]
  collection_ui: 'Hosted auth dialog (popup) — see components/tray-ai-components.yml'
  custom_oauth_apps: https://tray.ai/documentation/developer/getting-started/prerequisites/custom-oauth-apps
  note: >-
    Partners can white-label these with their own OAuth apps so end users see the partner's brand on
    the third-party consent screen, not Tray's.
agent_gateway_layers:
  client_authentication:
    - method: OAuth2
      note: Required for dynamic (user-provided) tool authentication. Tray currently names Claude Desktop as the supported OAuth2 client, with more expanding.
    - method: API token
      note: Static bearer; works with all MCP clients; cannot use dynamic authentication — tools must use service-account credentials.
  tool_authentication:
    - mode: service account
      note: One shared credential for every execution of the tool, whoever triggered it.
    - mode: dynamic (user-provided)
      note: The end user authenticates with their own credentials at runtime; actions execute with their permissions and are auditable to them. Mapping is valid for 7 days.
  access_management: >-
    Only users explicitly added on the MCP server's Access Management tab can execute its tools —
    workspace membership alone is not sufficient.
  docs: https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/authentication-and-access
regions:
  note: A token is region-bound. US api.tray.io / tray.io, EU api.eu1.tray.io / eu1.tray.io, APAC api.ap1.tray.io / ap1.tray.io.
gaps:
  - No OIDC discovery document — /.well-known/openid-configuration 404s on api.tray.io and auth.tray.io.
  - No scopes on the REST or GraphQL surfaces; a master token is all-or-nothing.
  - No documented token rotation or expiry policy for master and RBAC tokens.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com