Extole Authentication

generated: '2026-08-13'
method: searched
docs: https://docs.extole.com/reference/authentication-overview
source: >-
  https://docs.extole.com/reference/authentication-overview (upgraded from the 2026-07-19 derive over
  openapi/_original/*.json)
note: >-
  Upgraded from derived to searched. The OpenAPI documents declare only three apiKey schemes (header,
  cookie, query) and say nothing about token models, scopes, identity levels or the MCP surface — the
  spec is thin here and the docs carry the real contract. Extole runs THREE distinct credential models
  that the specs collapse into one: a server-side bearer access token, a rotating consumer access token
  with three identity levels, and OAuth 2.1 for the MCP server. All three are recorded.
summary:
  types:
  - apiKey
  - http
  - oauth2
  api_key_in:
  - header
  - cookie
  - query
  oauth2_flows:
  - authorization_code
  - client_credentials
  - refresh_token
  - token_exchange
  preferred: 'Authorization: Bearer <token>'
token_models:
- model: bearer-access-token
  apis:
  - Integration API - Server to Extole
  - Management API
  - Management Expert API
  caller: Brand backend services or admin tooling
  issued_to: the brand (client-scoped)
  create:
    ui: https://my.extole.com/security-center
    ui_path: Security Center -> Access Token -> + New Access Token
    api: POST /v4/tokens
    note: Security Center tokens are long-lived MANAGED tokens — named, listed and revoked rather than
      left to expire. Short-lived tokens for CI/CD are created programmatically.
  pass:
  - preferred: true
    method: header
    form: 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  - method: query
    form: '?access_token=YOUR_ACCESS_TOKEN'
    warning: Writes the token into logs and browser history.
  - method: cookie
    form: access_token=YOUR_ACCESS_TOKEN
    warning: Intended for consumer flows.
  example: |
    curl https://api.extole.io/v1/audiences \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
- model: consumer-access-token
  apis:
  - Integration API - Consumer to Extole
  caller: Browser or native app
  issued_to: the participant's session (issued and rotated by Extole)
  host: the brand program domain, NOT api.extole.io
  host_patterns:
  - https://{brand}.extole.io
  - https://share.{brand-domain} (brand-hosted CNAME)
  host_note: Find the active program domain in My Extole Tech Center. This is why the consumer spec's
    servers[] block is templated (https://{brand}.extole.io) — the host is per-brand by design, not a
    placeholder.
  identity_levels:
  - level: anonymous
    grants: Device-only token. Records journey activity without an identity profile.
  - level: identified
    grants: Associated with an email or partner_user_id. Can add journey information; cannot modify
      profile properties or read private profile data (last name, friend information, reward
      information). First name is public.
  - level: verified
    scope: VERIFIED_CONSUMER
    grants: Identity confirmed. Full profile access including updates.
  verification_methods:
  - method: jwt
    header: X-Extole-Jwt
    required_claim: 'scope: VERIFIED_CONSUMER'
    kid: Every JWT must carry a kid header matching the Partner Key ID on the key registered in My
      Extole.
    keys:
    - kind: hmac-shared-secret
      algorithms: [HS256, HS384, HS512]
    - kind: rsa-key-pair
      algorithms: [RS256, RS384, RS512, PS256, PS384, PS512]
      note: Brand uploads only the public key, DER base64 encoded.
    - kind: ec
      algorithms: [ES256, ES384, ES512]
    jwe: Encrypted JWTs (JWE) are accepted in the same header under the same key management.
    docs: https://docs.extole.com/docs/verifying-consumers
    failures: [jwt_error, jwt_authentication_error, invalid_access_token]
  - method: email
    description: Extole emails the participant a verification link; clicking it upgrades the token.
  - method: explicit-authorization
    description: OAuth Resource Owner Credential Grant, for experiences already behind a brand login.
  cookie_lifecycle: Managed by core.js during zone requests. When the platform binds an identity Extole
    rotates the cookie and returns a new token. The cookie is suppressed when cookie consent is not
    enabled for the program.
- model: oauth2-mcp
  apis:
  - Extole MCP Server
  caller: MCP client (Claude, Claude Code, Cursor, ChatGPT, Codex, or any MCP-compatible client)
  spec: OAuth 2.1 authorization code with PKCE (S256)
  issuer: https://idp.extole.com
  authorization_endpoint: https://idp.extole.com/oauth2/authorize
  token_endpoint: https://idp.extole.com/oauth2/token
  introspection_endpoint: https://idp.extole.com/oauth2/introspect
  revocation_endpoint: https://idp.extole.com/oauth2/revoke
  jwks_uri: https://idp.extole.com/oauth2/jwks
  scopes: [openid, profile, email]
  token_endpoint_auth_methods: [none, client_secret_post]
  dpop: true
  mtls_bound_tokens: true
  alternative: A My.Extole Access Token may be passed as a bearer credential for clients that do not
    support OAuth.
  revoke: https://my.extole.com/security-center#access-token
  docs: https://docs.extole.com/docs/mcp-authentication
  ref: mcp/extole-mcp.yml
schemes:
- name: HEADER
  type: apiKey
  in: header
  parameter: Authorization
  sources:
  - openapi/_original/extole-integration-consumer-to-extole-openapi.json
  - openapi/_original/extole-integration-server-to-extole-openapi.json
  - openapi/_original/extole-management-expert-openapi.json
  - openapi/_original/extole-management-openapi.json
- name: COOKIE
  type: apiKey
  in: cookie
  parameter: extole_token
  sources:
  - openapi/_original/extole-integration-consumer-to-extole-openapi.json
  - openapi/_original/extole-integration-server-to-extole-openapi.json
  - openapi/_original/extole-management-expert-openapi.json
  - openapi/_original/extole-management-openapi.json
- name: QUERY
  type: apiKey
  in: query
  parameter: access_token
  sources:
  - openapi/_original/extole-integration-consumer-to-extole-openapi.json
  - openapi/_original/extole-integration-server-to-extole-openapi.json
  - openapi/_original/extole-management-expert-openapi.json
  - openapi/_original/extole-management-openapi.json
- name: extole-mcp-oauth
  type: oauth2
  flows: [authorizationCode, clientCredentials, refreshToken, tokenExchange]
  sources:
  - well-known/extole-mcp-oauth-authorization-server.json
  - https://docs.extole.com/docs/mcp-authentication
scopes:
  ref: scopes/extole-scopes.yml
  rest: [CLIENT_ADMIN, CAMPAIGN_EDIT, USER_SUPPORT, ANY, VERIFIED_CONSUMER]
  mcp: [openid, profile, email]
  denied:
    status: 403
    code: scopes_denied
best_practices:
- Never embed a bearer access token in client-side code. Use consumer access tokens for browser and
  native-app integrations.
- Never commit a bearer token to a repository. Rotate immediately if exposed.
- Rotate JWT signing material on a schedule and when staff with access changes.
- Use scope minimization — a read-only integration should not carry CLIENT_ADMIN.
- Use managed tokens for service-to-service integrations; they are easier to inventory and revoke.
errors:
- {status: 401, code: method_unauthorized, cause: Missing, malformed, or expired token.}
- {status: 401, code: invalid_credentials, cause: Wrong email or password during token creation.}
- {status: 401, code: invalid_access_token, cause: Token does not match a known credential.}
- {status: 401, code: expired_access_token, cause: Token is past its expiration.}
- {status: 401, code: jwt_authentication_error, cause: JWT signature did not verify.}
- {status: 403, code: missing_access_token, cause: No access token in the request.}
- {status: 403, code: scopes_denied, cause: Token does not carry the required scope.}
- {status: 400, code: jwt_error, cause: JWT is malformed or has invalid claims.}
cross_links:
  scopes: scopes/extole-scopes.yml
  errors: errors/extole-error-codes.yml
  conventions: conventions/extole-conventions.yml
  sandbox: sandbox/extole-sandbox.yml
  mcp: mcp/extole-mcp.yml
x-evidence:
- fetched: '2026-08-13'
  url: https://docs.extole.com/reference/authentication-overview.md
  http_status: 200
- fetched: '2026-08-13'
  url: https://docs.extole.com/docs/mcp-authentication.md
  http_status: 200