Thebrief Authentication

generated: '2026-08-12'
method: searched
source: https://docs.thebrief.ai/public-api/authentication
docs:
  - https://docs.thebrief.ai/public-api/authentication
  - https://docs.thebrief.ai/public-api/rest-api/auth
  - https://docs.thebrief.ai/public-api
  - https://docs.thebrief.ai/app-integration
summary: >-
  The Brief Public API (REST at https://api.thebrief.ai/v1 and GraphQL at
  https://graphql.thebrief.ai/public) authenticates with a JWT bearer token minted from a
  clientId / clientSecret pair the team creates in the app under Manage account >
  API credentials. There is no OAuth 2.0 authorization server, no OpenID Connect
  discovery document and no mTLS surface; token scopes are carried in the token, not
  negotiated. The same clientId/secret pair also signs the session JWT used by the
  App Integration (embedded editor) flow.

credential_issuance:
  console_url: https://app.thebrief.ai/go-to/settings/api-credentials
  path_in_app: Profile > Manage account > API credentials
  credential_pair:
    - {name: clientId, type: uuid, role: public identifier}
    - {name: clientSecret, type: uuid, role: signing secret, note: Kept private; never shared client-side.}
  revocation:
    supported: true
    note: >-
      The docs warn that deleting an API key blocks every already-configured integration
      from accessing The Brief — deletion is the documented revocation mechanism.
    source: https://docs.thebrief.ai/zapier-integration

schemes:
  - id: rest_bearer_jwt
    type: http
    scheme: bearer
    bearerFormat: JWT
    header: Authorization
    value_format: 'Bearer <jwt>'
    applies_to: https://api.thebrief.ai/v1
    token_endpoint: https://api.thebrief.ai/v1/auth/token
    token_endpoint_method: POST
    token_request_body:
      - {name: clientId, required: true, type: string}
      - {name: clientSecret, required: true, type: string}
    token_response_field: token
    note: >-
      POST the clientId/clientSecret pair to /v1/auth/token and the API returns
      {"token": "<jwt>"} to send as Authorization: Bearer on every subsequent request.

  - id: graphql_bearer_jwt
    type: http
    scheme: bearer
    bearerFormat: JWT
    header: Authorization
    applies_to: https://graphql.thebrief.ai/public
    note: >-
      The GraphQL endpoint accepts the same bearer token. Anonymous __schema introspection
      IS permitted (verified 2026-08-12, HTTP 200) but executing queries/mutations is not.

  - id: self_signed_jwt
    type: jwt
    signing: HS256 (jsonwebtoken sign with the clientSecret)
    claims:
      - {name: clientId, required: true, description: The public clientId from API credentials.}
      - {name: iat, required: false, description: Issued-at timestamp.}
      - {name: userId, required: false, description: App Integration only — the team user to impersonate for the session.}
      - {name: action, required: false, description: App Integration only — the session action (create_design_from_template, create_blank_design, edit_design, get_share_link).}
      - {name: sessionConfig, required: false, description: App Integration only — UI configuration for the session.}
    note: >-
      Clients may sign their own JWT with the secret rather than calling /v1/auth/token.
      The App Integration (embedded editor) flow REQUIRES this form — the signed token is
      handed to https://app.thebrief.ai/tokenAuth?token=<jwt> (or app-proxy.thebrief.ai in
      an iframe) to open an impersonated editor session.
    source: https://docs.thebrief.ai/app-integration

token_scopes:
  model: api-token-scope
  note: >-
    Not OAuth 2.0 scopes. The public GraphQL schema publishes an ApiTokenScope enum naming
    the surfaces an API token may be issued against; this is the only scope vocabulary The
    Brief exposes, and it is captured verbatim from the live introspection response.
  source: graphql/thebrief-public.graphql (enum ApiTokenScope)
  scopes:
    - {name: CREATOPY_API, description: Access to Creatopy API}
    - {name: FIGMA, description: Access to Figma plugin}
    - {name: ZAPIER, description: Access to Zapier integration}

authorization:
  model: team-scoped
  admin_gated_operations:
    note: >-
      The GraphQL schema marks a set of team-administration fields as requiring admin access
      in their own descriptions (teamUsers, createTeamUser, deleteTeamUser, updateTeamUserRole).
      The InputAuthorization input type carries needAdmin and requiredScopes, confirming the
      server evaluates both an admin flag and a scope list per request.
    fields: [teamUsers, createTeamUser, deleteTeamUser, updateTeamUserRole]
  impersonation:
    supported: true
    note: >-
      A clientId/secret pair generated by a team owner or admin may impersonate any user on
      that team by putting their userId in the App Integration session JWT.

not_present:
  oauth2: {documented: false, note: No OAuth 2.0 authorization-code/client-credentials flow is documented.}
  openid_connect: {documented: false, probe: 'https://www.thebrief.ai/.well-known/openid-configuration -> 404 (also 404 on api., docs.)'}
  oauth_authorization_server_metadata: {documented: false, probe: 'https://api.thebrief.ai/.well-known/oauth-authorization-server -> 404'}
  mutual_tls: {documented: false}
  api_key_header: {documented: false, note: The "API key" named in the UI is the clientId/clientSecret pair, exchanged for a JWT — not a raw key header.}

cross_links:
  conventions: conventions/thebrief-conventions.yml
  errors: errors/thebrief-error-codes.yml
  rate_limits: rate-limits/thebrief-rate-limits.yml
  graphql: graphql/thebrief-public.graphql