CustomDomain Authentication

generated: '2026-11-04'
method: searched
source: https://docs.customdomain.ai/docs/authentication/overview
summary:
  types:
  - apiKey
  - http
  - oauth2
  api_key_in:
  - header
  oauth2_flows:
  - authorizationCode
schemes:
- name: managementKey
  type: http
  scheme: bearer
  description: Operator management key. Gates provisioning + reads across tenants.
  sources:
  - openapi/customdomain-ai-openapi.yml
- name: provisionSecret
  type: apiKey
  in: header
  parameter: X-Provision-Secret
  description: Narrow secret held by the customer console's server, for signup provisioning and its other server
    to server calls (also accepted as a Bearer token, except on POST /audit, where a Bearer is always a tenant credential).
  sources:
  - openapi/customdomain-ai-openapi.yml
- name: agentToken
  type: oauth2
  flows:
  - flow: authorizationCode
    authorizationUrl: https://api.customdomain.ai/oauth/agent/authorize
    tokenUrl: https://api.customdomain.ai/oauth/agent/token
    scopes: 4
  description: 'A delegated agent access token: an ES256 JWT that lives 15 minutes, sent as a bearer token. A person
    approves an agent in the console and the agent exchanges its authorization code (with PKCE) at the token endpoint.
    The token carries the workspace, the one application the grant is bound to, the grant, the approved scopes and
    its audience, and is verified against `/.well-known/jwks.json`. A route t'
  sources:
  - openapi/customdomain-ai-openapi.yml
- name: apiKey
  type: http
  scheme: bearer
  description: 'Long-lived tenant API key sent as Authorization: Bearer; prefix cd_live_ (production) or cd_test_
    (staging and development) followed by 32 lowercase hex characters; legacy sk_live_/sk_test_ keys still accepted.
    Stored only as a hash, shown once at creation.'
  sources:
  - https://docs.customdomain.ai/docs/authentication/overview
- name: widgetJWT
  type: http
  scheme: bearer
  description: Short-lived JWT minted server-side through POST /v1/tokens with the application's client secret;
    scoped to one application and optionally one domain; the only credential that reaches the browser.
  sources:
  - https://docs.customdomain.ai/docs/authentication/overview
docs: https://docs.customdomain.ai/docs/authentication/overview
docs_pages:
- https://docs.customdomain.ai/docs/authentication/overview
- https://docs.customdomain.ai/docs/authentication/widget-tokens
- https://docs.customdomain.ai/docs/agents/oauth-flow
key_prefixes:
  live: cd_live_
  test: cd_test_
  legacy:
  - sk_live_
  - sk_test_
  note: 'The prefix is not the mode: a cd_test_ key works on real domains; a key is a test mode key only when its
    application was made with "sandbox": true.'
token_lifetimes:
  agent_token: 15 minutes (ES256 JWT, rotating refresh token)
roles:
- owner
- admin
- member
- viewer