openapi: 3.0.1 info: description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.' title: Integration API - Consumer to Extole Audiences Authentication API version: '1.0' servers: - description: Production url: https://{brand}.extole.io variables: brand: default: yourcompany description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io) security: - HEADER: [] - QUERY: [] - COOKIE: [] tags: - name: Authentication paths: /api/v5/token: get: description: Returns the metadata for the access token supplied in the `access_token` query parameter or bearer header. If no token is supplied, the server attempts to resolve a token from the HTTP authorization header. Returns the token's expiry, scopes, and the identity it represents. operationId: getConsumerToken responses: '200': content: application/json: schema: $ref: '#/components/schemas/TokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' expired_access_token: $ref: '#/components/examples/expired_access_token' invalid_access_token: $ref: '#/components/examples/invalid_access_token' jwt_authentication_error: $ref: '#/components/examples/jwt_authentication_error' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Get consumer token details tags: - Authentication x-extole-bundle: integration-consumer-to-extole x-extole-visibility: visible post: description: Issues a new access token for the identity supplied in the request. Pass an `email` to identify a consumer when the client identity key is `email`. Pass a `jwt` to assert a trusted identity via JWT verification. Omit both to issue an anonymous token. The optional `duration_seconds` field caps the token lifetime. operationId: createConsumerToken requestBody: content: application/json: example: duration_seconds: 1 email: email jwt: jwt schema: $ref: '#/components/schemas/CreateTokenRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateTokenRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TokenResponse' description: Created consumer access token. '400': content: application/json: examples: email_not_applicable: $ref: '#/components/examples/email_not_applicable' invalid_access_token_duration: $ref: '#/components/examples/invalid_access_token_duration' schema: $ref: '#/components/schemas/RestExceptionResponse' description: 'The token-creation request is invalid: `email` is not applicable for the client''s identity key (`email_not_applicable`), or the requested token duration is outside the permitted range (`invalid_access_token_duration`).' '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '403': content: application/json: examples: email_mismatch: $ref: '#/components/examples/email_mismatch' invalid_email: $ref: '#/components/examples/invalid_email' jwt_error: $ref: '#/components/examples/jwt_error' method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Create a consumer access token tags: - Authentication x-extole-bundle: integration-consumer-to-extole x-extole-visibility: visible delete: description: Revokes the access token supplied in the `access_token` query parameter or bearer header. If no token is supplied, the server attempts to resolve a token from the HTTP authorization header and revokes that one. After revocation the token is immediately invalidated. operationId: deleteConsumerToken responses: '200': content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' expired_access_token: $ref: '#/components/examples/expired_access_token' invalid_access_token: $ref: '#/components/examples/invalid_access_token' jwt_authentication_error: $ref: '#/components/examples/jwt_authentication_error' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Delete a consumer access token tags: - Authentication x-extole-bundle: integration-consumer-to-extole x-extole-visibility: visible /v4/tokens: get: description: Returns the metadata for the access token used to authenticate the request (`type`, `client_id`, `identity_id`, `expires_in`, `scopes`). Equivalent to `GET /v4/tokens/{token}` but without having to repeat the token in the URL path. operationId: getCurrentClientAccessToken responses: '200': content: application/json: schema: $ref: '#/components/schemas/AccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Get current access token tags: - Authentication x-extole-bundle: integration-server-to-extole x-extole-visibility: visible post: description: 'Mints a bearer token for server-to-Extole calls by a client. The body is optional: when omitted, the new token mirrors the calling identity''s scopes; when supplied, the body can narrow the scope set (subset of the caller''s scopes), bind the token to a specific `client_id`, supply email/password credentials in lieu of a calling token, or override the default lifetime via `duration_seconds`. Returns the new token, its `expires_in` (seconds), the resolved `client_id`, the `identity_id` of the user the token represents, and the granted `scopes`.' operationId: createClientAccessToken requestBody: content: application/json: example: client_id: client_id duration_seconds: 1 email: email password: password scopes: - BACKEND schema: $ref: '#/components/schemas/AccessTokenCreationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AccessTokenResponse' description: Access token created. '400': content: application/json: examples: invalid_client_id: $ref: '#/components/examples/invalid_client_id' invalid_duration: $ref: '#/components/examples/invalid_duration' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad request. The named examples below cover this operation's input-validation errors. Other 400 causes include malformed JSON and missing required fields - inspect the response `code` field for the specific error. '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: invalid_credentials: $ref: '#/components/examples/invalid_credentials' missing_credentials: $ref: '#/components/examples/missing_credentials' scopes_denied: $ref: '#/components/examples/scopes_denied' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Authentication failed. The named examples below cover the most common credential rejections; other 403 causes (account locked, account disabled, requested scopes that exceed the calling identity's privileges) are auto-derived - inspect the response `code` field for the specific error. '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Create access token tags: - Authentication x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v4/tokens/{token}: get: description: Returns the metadata for the supplied token value (`type`, `client_id`, `identity_id`, `expires_in`, `scopes`). Use this when the caller has the token string and needs to introspect it; for the calling identity's own active token use `GET /v4/tokens` instead. operationId: getClientAccessTokenByValue parameters: - in: path name: token required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Get access token by value tags: - Authentication x-extole-bundle: integration-server-to-extole x-extole-visibility: visible delete: description: Invalidates the supplied access token immediately. Subsequent requests using the same token return `401 invalid_access_token`. Returns `200` with an empty body on success. operationId: deleteClientAccessToken parameters: - in: path name: token required: true schema: type: string responses: '200': description: Token invalidated. '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Invalidate access token tags: - Authentication x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v4/tokens/exchange/{token}: put: description: Exchanges the supplied access token for a fresh one with the same scopes and a renewed expiry. The original token is invalidated immediately on success. Use this to rotate long-lived integration tokens without re-authenticating. operationId: exchangeClientAccessToken parameters: - in: path name: token required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Exchange access token tags: - Authentication x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v4/tokens/resource: get: description: Returns the resource-scoped access token associated with the current credentials. operationId: getResourceToken responses: '200': content: application/json: schema: $ref: '#/components/schemas/ResourceAccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Get resource access token tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v2/consumers/{accessToken}/authorize: post: description: Upgrades an anonymous consumer access token to an authenticated token by associating it with a verified consumer identity. Returns the upgraded consumer token. operationId: upgradeConsumerAuthorization parameters: - in: path name: accessToken required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConsumerTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' consumer_token_invalid: $ref: '#/components/examples/consumer_token_invalid' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' consumer_token_upgrade_not_allowed: $ref: '#/components/examples/consumer_token_upgrade_not_allowed' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Upgrade consumer authorization tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v2/consumers/{personId}/token: post: description: Creates a consumer access token for the specified person id. Returns the new consumer token. operationId: createConsumerAuthorization parameters: - in: path name: personId required: true schema: format: int64 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConsumerTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' person_not_found: $ref: '#/components/examples/person_not_found' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Create consumer authorization tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v4/oauth/tokens: post: description: Exchanges OAuth client credentials (client_id and client_secret) for an API access token using the client credentials grant flow. Returns the access token and expiry information. operationId: createOAuthClientCredentialsToken requestBody: content: application/x-www-form-urlencoded: example: client_id: client_id client_secret: client_secret grant_type: grant_type scope: scope schema: properties: client_id: type: string client_secret: type: string grant_type: type: string scope: nullable: true type: string type: object responses: '200': content: application/json: schema: $ref: '#/components/schemas/OAuthAccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_client_id: $ref: '#/components/examples/invalid_client_id' invalid_duration: $ref: '#/components/examples/invalid_duration' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' invalid_user_id: $ref: '#/components/examples/invalid_user_id' missing_request_body: $ref: '#/components/examples/missing_request_body' unsupported_grant_type: $ref: '#/components/examples/unsupported_grant_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' account_disabled: $ref: '#/components/examples/account_disabled' account_locked: $ref: '#/components/examples/account_locked' expired_credentials: $ref: '#/components/examples/expired_credentials' invalid_credentials: $ref: '#/components/examples/invalid_credentials' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' missing_credentials: $ref: '#/components/examples/missing_credentials' scopes_denied: $ref: '#/components/examples/scopes_denied' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Create OAuth client credentials token tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v4/tokens/managed/openid-connect/authorization-code-flow: post: description: Creates a managed access token by exchanging an OpenID Connect authorization code. Returns the created token. operationId: createManagedTokenViaAuthorizationCode parameters: - in: header name: X-CSRF-TOKEN schema: type: string - in: header name: X-NONCE schema: type: string requestBody: content: application/json: example: code: code duration_seconds: 1 name: name scopes: - BACKEND state: state schema: $ref: '#/components/schemas/AuthCodeManagedAccessTokenCreationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_duration: $ref: '#/components/examples/invalid_duration' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' maximum_name_length: $ref: '#/components/examples/maximum_name_length' missing_request_body: $ref: '#/components/examples/missing_request_body' no_such_managed_token: $ref: '#/components/examples/no_such_managed_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' account_disabled: $ref: '#/components/examples/account_disabled' account_locked: $ref: '#/components/examples/account_locked' authorization_code_missing_code: $ref: '#/components/examples/authorization_code_missing_code' authorization_code_missing_csrf_token: $ref: '#/components/examples/authorization_code_missing_csrf_token' authorization_code_missing_nonce: $ref: '#/components/examples/authorization_code_missing_nonce' authorization_code_missing_state: $ref: '#/components/examples/authorization_code_missing_state' authorization_code_response_invalid: $ref: '#/components/examples/authorization_code_response_invalid' expired_credentials: $ref: '#/components/examples/expired_credentials' invalid_credentials: $ref: '#/components/examples/invalid_credentials' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' missing_credentials: $ref: '#/components/examples/missing_credentials' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Create a managed token via authorization code tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v4/tokens/openid-connect/authorization-code-flow: post: description: 'Exchanges an OpenID Connect authorization-code response for an Extole access token. Pair the body''s `code` and `state` with the `X-CSRF-TOKEN` and `X-NONCE` headers - all four are required by the OIDC validator. Marked as `expert`: most integrators authenticate via `POST /v4/tokens` instead.' operationId: exchangeAuthorizationCode parameters: - in: header name: X-CSRF-TOKEN schema: type: string - in: header name: X-NONCE schema: type: string requestBody: content: application/json: example: code: code state: state schema: $ref: '#/components/schemas/AuthCodeResponseValidateRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_client_id: $ref: '#/components/examples/invalid_client_id' invalid_duration: $ref: '#/components/examples/invalid_duration' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' invalid_user_id: $ref: '#/components/examples/invalid_user_id' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' account_disabled: $ref: '#/components/examples/account_disabled' account_locked: $ref: '#/components/examples/account_locked' authorization_code_missing_auth_provider_type_id: $ref: '#/components/examples/authorization_code_missing_auth_provider_type_id' authorization_code_missing_code: $ref: '#/components/examples/authorization_code_missing_code' authorization_code_missing_csrf_token: $ref: '#/components/examples/authorization_code_missing_csrf_token' authorization_code_missing_nonce: $ref: '#/components/examples/authorization_code_missing_nonce' authorization_code_missing_state: $ref: '#/components/examples/authorization_code_missing_state' authorization_code_response_invalid: $ref: '#/components/examples/authorization_code_response_invalid' expired_credentials: $ref: '#/components/examples/expired_credentials' invalid_credentials: $ref: '#/components/examples/invalid_credentials' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_credentials: $ref: '#/components/examples/missing_credentials' scopes_denied: $ref: '#/components/examples/scopes_denied' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Exchange OIDC authorization code tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v4/tokens/openid-connect/idp-initiated-authorization-code-flow: post: description: Validates an authorization code returned by an IdP-initiated OpenID Connect SSO flow and exchanges it for an Extole access token. Expert-only; most integrators use `POST /v4/tokens` instead. operationId: validateIdpInitiated requestBody: content: application/json: example: auth_provider_type_id: auth_provider_type_id code: code schema: $ref: '#/components/schemas/IdpInitiatedAuthCodeResponseValidateRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_client_id: $ref: '#/components/examples/invalid_client_id' invalid_duration: $ref: '#/components/examples/invalid_duration' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' invalid_user_id: $ref: '#/components/examples/invalid_user_id' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' account_disabled: $ref: '#/components/examples/account_disabled' account_locked: $ref: '#/components/examples/account_locked' authorization_code_missing_auth_provider_type_id: $ref: '#/components/examples/authorization_code_missing_auth_provider_type_id' authorization_code_missing_code: $ref: '#/components/examples/authorization_code_missing_code' authorization_code_missing_csrf_token: $ref: '#/components/examples/authorization_code_missing_csrf_token' authorization_code_missing_nonce: $ref: '#/components/examples/authorization_code_missing_nonce' authorization_code_missing_state: $ref: '#/components/examples/authorization_code_missing_state' authorization_code_response_invalid: $ref: '#/components/examples/authorization_code_response_invalid' expired_credentials: $ref: '#/components/examples/expired_credentials' invalid_credentials: $ref: '#/components/examples/invalid_credentials' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_credentials: $ref: '#/components/examples/missing_credentials' scopes_denied: $ref: '#/components/examples/scopes_denied' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Exchange an IdP-initiated OIDC authorization code tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v6/security/oauth/flow/exchange: post: description: Exchanges an OAuth authorization code for an access token using the authorization code flow. Returns the access token and associated session information. operationId: exchangeOAuthCode requestBody: content: application/json: example: client_key_id: client_key_id code: code key_type: STANDARD redirect_uri: redirect_uri schema: $ref: '#/components/schemas/OAuthFlowCodeExchangeRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/OAuthFlowCodeExchangeResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' client_key_already_exists: $ref: '#/components/examples/client_key_already_exists' client_key_exchanger_not_found: $ref: '#/components/examples/client_key_exchanger_not_found' exchange_client_key_not_found: $ref: '#/components/examples/exchange_client_key_not_found' exchanged_client_key_creation_failed: $ref: '#/components/examples/exchanged_client_key_creation_failed' invalid_key_exchange_response: $ref: '#/components/examples/invalid_key_exchange_response' key_exchange_exception: $ref: '#/components/examples/key_exchange_exception' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Exchange OAuth authorization code tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v4/tokens/resource/{access_token_to_delete}: delete: description: Revokes the specified resource-scoped access token. operationId: deleteResourceToken parameters: - description: Resource-scoped access token to revoke. in: path name: access_token_to_delete required: true schema: type: string responses: '200': description: Resource access token revoked. This response has no body. '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_duration: $ref: '#/components/examples/invalid_duration' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' maximum_name_length: $ref: '#/components/examples/maximum_name_length' missing_request_body: $ref: '#/components/examples/missing_request_body' no_such_managed_token: $ref: '#/components/examples/no_such_managed_token' no_such_resource_token: $ref: '#/components/examples/no_such_resource_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' account_disabled: $ref: '#/components/examples/account_disabled' account_locked: $ref: '#/components/examples/account_locked' authorization_code_missing_code: $ref: '#/components/examples/authorization_code_missing_code' authorization_code_missing_csrf_token: $ref: '#/components/examples/authorization_code_missing_csrf_token' authorization_code_missing_nonce: $ref: '#/components/examples/authorization_code_missing_nonce' authorization_code_missing_state: $ref: '#/components/examples/authorization_code_missing_state' authorization_code_response_invalid: $ref: '#/components/examples/authorization_code_response_invalid' expired_credentials: $ref: '#/components/examples/expired_credentials' invalid_credentials: $ref: '#/components/examples/invalid_credentials' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' missing_credentials: $ref: '#/components/examples/missing_credentials' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Delete a resource access token tags: - Authentication x-extole-bundle: management-expert x-extole-visibility: expert /v2/consumers/{accessToken}/debug: get: description: Returns metadata for a consumer (person) access token by value, including tokens that are expired or invalidated. Distinct from client access token debug (`GET /v4/tokens/{token}/debug`) and managed API tokens (`/v4/tokens/managed`). Requires a user access token with the `CLIENT_ADMIN` scope. operationId: debugConsumerAccessToken parameters: - in: path name: accessToken required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConsumerTokenDetailsResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Debug consumer access token tags: - Authentication x-extole-bundle: management x-extole-visibility: visible /v4/tokens/managed: get: description: Returns all managed API access tokens for the client. operationId: listManagedTokens responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/ManagedAccessTokenResponse' type: array description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' missing_request_body: $ref: '#/components/examples/missing_request_body' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: List managed access tokens tags: - Authentication x-extole-bundle: management x-extole-visibility: visible post: description: Creates a new server-generated managed API access token with configurable scopes and expiry. Returns the created token with its server-assigned id. operationId: createManagedToken requestBody: content: application/json: example: duration_seconds: 1 name: name password: password scopes: - BACKEND schema: $ref: '#/components/schemas/ManagedAccessTokenCreationRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAccessTokenResponse' description: Successful response '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_duration: $ref: '#/components/examples/invalid_duration' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' maximum_name_length: $ref: '#/components/examples/maximum_name_length' missing_request_body: $ref: '#/components/examples/missing_request_body' no_such_managed_token: $ref: '#/components/examples/no_such_managed_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' account_disabled: $ref: '#/components/examples/account_disabled' account_locked: $ref: '#/components/examples/account_locked' authorization_code_missing_code: $ref: '#/components/examples/authorization_code_missing_code' authorization_code_missing_csrf_token: $ref: '#/components/examples/authorization_code_missing_csrf_token' authorization_code_missing_nonce: $ref: '#/components/examples/authorization_code_missing_nonce' authorization_code_missing_state: $ref: '#/components/examples/authorization_code_missing_state' authorization_code_response_invalid: $ref: '#/components/examples/authorization_code_response_invalid' expired_credentials: $ref: '#/components/examples/expired_credentials' invalid_credentials: $ref: '#/components/examples/invalid_credentials' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' missing_credentials: $ref: '#/components/examples/missing_credentials' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Create a managed access token tags: - Authentication x-extole-bundle: management x-extole-visibility: visible /v4/tokens/managed/{access_token_id}: delete: description: Revokes and removes the managed API access token for the specified id. operationId: deleteManagedToken parameters: - in: path name: access_token_id required: true schema: type: string responses: '200': description: Managed access token deleted. '400': content: application/json: examples: binding_error: $ref: '#/components/examples/binding_error' invalid_duration: $ref: '#/components/examples/invalid_duration' invalid_json: $ref: '#/components/examples/invalid_json' invalid_parameter: $ref: '#/components/examples/invalid_parameter' maximum_name_length: $ref: '#/components/examples/maximum_name_length' missing_request_body: $ref: '#/components/examples/missing_request_body' no_such_managed_token: $ref: '#/components/examples/no_such_managed_token' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Bad Request '401': content: application/json: examples: method_unauthorized: $ref: '#/components/examples/method_unauthorized' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unauthorized '402': content: application/json: examples: payment_required: $ref: '#/components/examples/payment_required' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Payment Required '403': content: application/json: examples: access_denied: $ref: '#/components/examples/access_denied' account_disabled: $ref: '#/components/examples/account_disabled' account_locked: $ref: '#/components/examples/account_locked' authorization_code_missing_code: $ref: '#/components/examples/authorization_code_missing_code' authorization_code_missing_csrf_token: $ref: '#/components/examples/authorization_code_missing_csrf_token' authorization_code_missing_nonce: $ref: '#/components/examples/authorization_code_missing_nonce' authorization_code_missing_state: $ref: '#/components/examples/authorization_code_missing_state' authorization_code_response_invalid: $ref: '#/components/examples/authorization_code_response_invalid' expired_credentials: $ref: '#/components/examples/expired_credentials' invalid_credentials: $ref: '#/components/examples/invalid_credentials' method_unauthorized: $ref: '#/components/examples/method_unauthorized' missing_access_token: $ref: '#/components/examples/missing_access_token' missing_credentials: $ref: '#/components/examples/missing_credentials' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Forbidden '415': content: application/json: examples: unsupported_media_type: $ref: '#/components/examples/unsupported_media_type' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Unsupported Media Type '429': content: application/json: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests summary: Delete a managed access token tags: - Authentication x-extole-bundle: management x-extole-visibility: visible components: examples: authorization_code_missing_csrf_token: summary: authorization_code_missing_csrf_token value: code: authorization_code_missing_csrf_token http_status_code: 403 message: Authorization Code Flow required csrf token header is missing parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_json: summary: invalid_json value: code: invalid_json http_status_code: 400 message: JSON is invalid parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 consumer_token_invalid: summary: consumer_token_invalid value: code: consumer_token_invalid http_status_code: 400 message: Provided consumer access token is not valid parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 no_such_resource_token: summary: no_such_resource_token value: code: no_such_resource_token http_status_code: 400 message: The access_token provided is could not be found. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 expired_access_token: summary: expired_access_token value: code: expired_access_token http_status_code: 403 message: The access_token provided with this request has expired. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_key_exchange_response: summary: invalid_key_exchange_response value: code: invalid_key_exchange_response http_status_code: 403 message: Received invalid response when exchange code to access token parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 missing_access_token: summary: missing_access_token value: code: missing_access_token http_status_code: 403 message: No access_token was provided with this request. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 key_exchange_exception: summary: key_exchange_exception value: code: key_exchange_exception http_status_code: 403 message: Failed to exchange code parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 payment_required: summary: payment_required value: code: payment_required http_status_code: 402 message: The access_token provided is associated with an unpaid account. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 consumer_token_upgrade_not_allowed: summary: consumer_token_upgrade_not_allowed value: code: consumer_token_upgrade_not_allowed http_status_code: 403 message: Could not upgrade provided access token parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 authorization_code_missing_nonce: summary: authorization_code_missing_nonce value: code: authorization_code_missing_nonce http_status_code: 403 message: Authorization Code Flow required nonce header is missing parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 jwt_authentication_error: summary: jwt_authentication_error value: code: jwt_authentication_error http_status_code: 403 message: The jwt authentication failed. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 exchanged_client_key_creation_failed: summary: exchanged_client_key_creation_failed value: code: exchanged_client_key_creation_failed http_status_code: 403 message: Failed to create a client key using exchanged access token parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 client_key_exchanger_not_found: summary: client_key_exchanger_not_found value: code: client_key_exchanger_not_found http_status_code: 403 message: Failed to exchange code to an access token, client key exchanger not found parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 unsupported_media_type: summary: unsupported_media_type value: code: unsupported_media_type http_status_code: 415 message: Request had an unsupported or no media type parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 method_unauthorized: summary: method_unauthorized value: code: method_unauthorized http_status_code: 401 message: Unauthorized access to this endpoint parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 account_disabled: summary: account_disabled value: code: account_disabled http_status_code: 403 message: The credentials provided with this request are invalid. Account has been disabled. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 jwt_error: summary: jwt_error value: code: jwt_error http_status_code: 403 message: The jwt authentication verification failed. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_access_token: summary: invalid_access_token value: code: invalid_access_token http_status_code: 403 message: The access_token provided with this request is invalid. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 unsupported_grant_type: summary: unsupported_grant_type value: code: unsupported_grant_type http_status_code: 400 message: Unsupported grant_type parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_duration: summary: invalid_duration value: code: invalid_duration http_status_code: 400 message: The requested duration for this token must end within the first ten millenium parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 no_such_managed_token: summary: no_such_managed_token value: code: no_such_managed_token http_status_code: 400 message: The access_token provided is could not be found. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 missing_request_body: summary: missing_request_body value: code: missing_request_body http_status_code: 400 message: Missing request body parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 authorization_code_missing_code: summary: authorization_code_missing_code value: code: authorization_code_missing_code http_status_code: 403 message: Authorization Code Flow required code parameter is missing parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 scopes_denied: summary: scopes_denied value: code: scopes_denied http_status_code: 403 message: Requested scopes is not a subset of current scopes. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 binding_error: summary: binding_error value: code: binding_error http_status_code: 400 message: Argument is not of the expected type parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 access_denied: summary: access_denied value: code: access_denied http_status_code: 403 message: The access_token provided is not permitted to access the specified resource. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 email_mismatch: summary: email_mismatch value: code: email_mismatch http_status_code: 403 message: Mismatch in specified emails parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 exchange_client_key_not_found: summary: exchange_client_key_not_found value: code: exchange_client_key_not_found http_status_code: 403 message: Exchange ClientKey not found parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 too_many_requests: summary: too_many_requests value: code: too_many_requests http_status_code: 429 message: The server is unable to process your request at the moment, please retry later. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_user_id: summary: invalid_user_id value: code: invalid_user_id http_status_code: 400 message: Invalid user id parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 authorization_code_missing_auth_provider_type_id: summary: authorization_code_missing_auth_provider_type_id value: code: authorization_code_missing_auth_provider_type_id http_status_code: 403 message: IdP initiated Authorization Code Flow required auth_provider_type_id parameter is missing parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_parameter: summary: invalid_parameter value: code: invalid_parameter http_status_code: 400 message: Parameter is invalid. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_access_token_duration: summary: invalid_access_token_duration value: code: invalid_access_token_duration http_status_code: 400 message: The duration provided with this request is invalid. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 account_locked: summary: account_locked value: code: account_locked http_status_code: 403 message: The credentials provided with this request are invalid. Account has been locked. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 person_not_found: summary: person_not_found value: code: person_not_found http_status_code: 403 message: Person not found parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 client_key_already_exists: summary: client_key_already_exists value: code: client_key_already_exists http_status_code: 403 message: Client key for this integration already exists parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_email: summary: invalid_email value: code: invalid_email http_status_code: 400 message: Invalid email parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 missing_credentials: summary: missing_credentials value: code: missing_credentials http_status_code: 403 message: No credentials provided with this request. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_credentials: summary: invalid_credentials value: code: invalid_credentials http_status_code: 403 message: The credentials provided with this request are invalid. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 expired_credentials: summary: expired_credentials value: code: expired_credentials http_status_code: 403 message: The credentials provided with this request are expired. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_client_id: summary: invalid_client_id value: code: invalid_client_id http_status_code: 400 message: Invalid client id parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 email_not_applicable: summary: email_not_applicable value: code: email_not_applicable http_status_code: 400 message: Email attribute is not applicable for current identity key parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 maximum_name_length: summary: maximum_name_length value: code: maximum_name_length http_status_code: 400 message: Name cannot be null, empty or blank and cannot be too long parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 authorization_code_response_invalid: summary: authorization_code_response_invalid value: code: authorization_code_response_invalid http_status_code: 403 message: Authorization Code Response is invalid or expired. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 authorization_code_missing_state: summary: authorization_code_missing_state value: code: authorization_code_missing_state http_status_code: 403 message: Authorization Code Flow required state parameter is missing parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 schemas: OAuthFlowCodeExchangeRequest: properties: client_key_id: type: string code: type: string key_type: enum: - STANDARD type: string redirect_uri: type: string required: - client_key_id - code - redirect_uri type: object AccessTokenResponse: description: Access-token metadata returned by `POST /v4/tokens`, `POST /v4/tokens/openid-connect/authorization-code-flow`, `GET /v4/tokens`, `GET /v4/tokens/{token}`, and `PUT /v4/tokens/exchange/{token}`. Pass `access_token` in the `Authorization` header (`Bearer ...`) on subsequent requests. properties: access_token: description: 'Token string. Send as `Authorization: Bearer ` on subsequent requests, or as the `access_token` query parameter / `extole_token` cookie.' type: string client_id: description: Stable Extole identifier for the client (tenant) this token authenticates against. type: string expires_in: description: Seconds until this token expires. Once expired, requests using it return `401 invalid_access_token`; rotate via `PUT /v4/tokens/exchange/{token}` before expiry to keep long-lived integrations alive. format: int64 type: integer identity_id: description: Stable Extole identifier for the identity (user, managed identity, or resource) that this token represents. type: string person_id: deprecated: true description: Deprecated alias for `identity_id`. New integrations should use `identity_id`. type: string scopes: description: Authorization scopes granted to this token. Determines which API operations the token may invoke. items: description: Authorization scopes granted to this token. Determines which API operations the token may invoke. enum: - BACKEND - CLIENT_ADMIN - CLIENT_REPORT_DOWNLOAD - CLIENT_SUPERUSER - ONE_TIME - PASSWORD_RESET - UPDATE_PROFILE - USER_SUPPORT - VERIFIED_CONSUMER type: string type: array uniqueItems: true type: description: Authentication shape backing the token. `USER` represents a human dashboard user, `MANAGED` an OAuth-style managed identity, and `RESOURCE` a scoped per-resource token. enum: - MANAGED - RESOURCE - USER type: string type: object AuthCodeManagedAccessTokenCreationRequest: properties: code: type: string duration_seconds: format: int64 nullable: true type: integer name: type: string scopes: items: enum: - BACKEND - CLIENT_ADMIN - CLIENT_REPORT_DOWNLOAD - CLIENT_SUPERUSER - ONE_TIME - PASSWORD_RESET - UPDATE_PROFILE - USER_SUPPORT - VERIFIED_CONSUMER type: string nullable: true type: array uniqueItems: true state: type: string required: - code - duration_seconds - name - scopes - state type: object ConsumerTokenDetailsResponse: properties: access_token: description: Opaque consumer access token these details describe. type: string client_id: description: Identifier of the client that owns the token. type: string expired: description: True when the token is no longer valid, whether it lapsed on its own or was invalidated. type: boolean expires_at: $ref: '#/components/schemas/ZonedDateTime' invalidated: description: True when the token was explicitly invalidated (revoked), as opposed to expiring on its own. Detected when updated_at is later than expires_at. type: boolean person_id: description: Identifier of the person the token represents. type: string scopes: description: Permission scopes granted to the token. items: description: Permission scopes granted to the token. type: string type: array uniqueItems: true updated_at: $ref: '#/components/schemas/ZonedDateTime' required: - access_token - client_id - expired - expires_at - invalidated - person_id - scopes - updated_at type: object IdpInitiatedAuthCodeResponseValidateRequest: properties: auth_provider_type_id: type: string code: type: string required: - auth_provider_type_id - code type: object TokenResponse: properties: access_token: description: Opaque access token for the consumer session. Pass as a Bearer token or `access_token` query parameter on subsequent requests. type: string expires_in: description: Seconds until the token expires. format: int64 type: integer scopes: description: Set of permission scopes granted to this token. items: description: Set of permission scopes granted to this token. enum: - UPDATE_PROFILE - VERIFIED_CONSUMER type: string type: array uniqueItems: true required: - access_token - expires_in - scopes type: object AccessTokenCreationRequest: description: Optional body for `POST /v4/tokens`. Omit the body entirely to mirror the calling identity's scopes; supply a body to bind the new token to a specific `client_id`, narrow its `scopes`, override the default lifetime via `duration_seconds`, or authenticate with email/password credentials in lieu of a calling token. properties: client_id: description: Stable Extole identifier for the client (tenant) the new token should authenticate against. Required when authenticating with email/password credentials; optional when the calling identity already implies the client. type: string duration_seconds: description: Override the default token lifetime, in seconds. Must keep the token's expiry within the next ten millennia; out-of-range values return `400 invalid_duration` with the default lifetime in `default_duration`. format: int64 nullable: true type: integer email: description: Email address of the dashboard user to authenticate. Pair with `password`. Returns `403 invalid_credentials` if the pair is wrong. nullable: true type: string password: description: Password for the dashboard user identified by `email`. Returns `403 invalid_credentials` if wrong, `403 expired_credentials` if expired, `403 account_locked` if the account is locked, and `403 account_disabled` if disabled. nullable: true type: string scopes: description: Subset of the calling identity's scopes to grant on the new token. Must be a strict subset; requesting a privilege the caller does not hold returns `403 scopes_denied` with the offending scopes in `denied_scopes`. Omit to mirror the caller's scopes. items: description: Subset of the calling identity's scopes to grant on the new token. Must be a strict subset; requesting a privilege the caller does not hold returns `403 scopes_denied` with the offending scopes in `denied_scopes`. Omit to mirror the caller's scopes. enum: - BACKEND - CLIENT_ADMIN - CLIENT_REPORT_DOWNLOAD - CLIENT_SUPERUSER - ONE_TIME - PASSWORD_RESET - UPDATE_PROFILE - USER_SUPPORT - VERIFIED_CONSUMER type: string nullable: true type: array uniqueItems: true required: - client_id - duration_seconds - email - password - scopes type: object AccessTokenResourceResponse: properties: id: type: string type: enum: - PUBLIC_REPORT type: string type: object OAuthAccessTokenResponse: properties: access_token: type: string expires_in: format: int64 type: integer token_type: type: string required: - access_token - expires_in - token_type type: object ConsumerTokenResponse: properties: access_token: type: string client_id: type: string scopes: items: type: string type: array uniqueItems: true required: - access_token - client_id - scopes type: object ManagedAccessTokenResponse: properties: access_token: type: string access_token_id: type: string access_token_response: $ref: '#/components/schemas/AccessTokenResponse' client_id: type: string create_date: $ref: '#/components/schemas/ZonedDateTime' created_at: format: int64 type: integer expire_date: $ref: '#/components/schemas/ZonedDateTime' expires_in: format: int64 type: integer name: type: string required: - access_token - access_token_id - access_token_response - client_id - create_date - created_at - expire_date - expires_in - name type: object ManagedAccessTokenCreationRequest: properties: duration_seconds: format: int64 type: integer name: type: string password: type: string scopes: items: enum: - BACKEND - CLIENT_ADMIN - CLIENT_REPORT_DOWNLOAD - CLIENT_SUPERUSER - ONE_TIME - PASSWORD_RESET - UPDATE_PROFILE - USER_SUPPORT - VERIFIED_CONSUMER type: string type: array uniqueItems: true required: - password type: object ResourceAccessTokenResponse: properties: access_token: type: string expires_in: format: int64 type: integer identity_id: type: string resources: items: $ref: '#/components/schemas/AccessTokenResourceResponse' type: array required: - access_token - expires_in - identity_id - resources type: object CreateTokenRequest: properties: duration_seconds: description: Requested token lifetime in seconds. Defaults to the client configuration value when omitted. format: int64 nullable: true type: integer email: description: Email address used to identify or create the consumer. Ignored when `jwt` is present. nullable: true type: string jwt: description: Signed JWT carrying consumer identity claims. When supplied, identity is derived from the token claims rather than from `email`. nullable: true type: string required: - duration_seconds - email - jwt type: object OAuthFlowCodeExchangeResponse: properties: client_key_id: type: string required: - client_key_id type: object AuthCodeResponseValidateRequest: description: Body of `POST /v4/tokens/openid-connect/authorization-code-flow`. Pair with the `X-CSRF-TOKEN` and `X-NONCE` headers minted alongside the authorization-code response. properties: code: description: Authorization code received from the OpenID Connect provider. Validated alongside the `X-CSRF-TOKEN` and `X-NONCE` headers; missing or expired codes return `403 authorization_code_response_invalid`. type: string state: description: Opaque state value the relying party round-tripped through the authorization-code flow. Must match the value the relying party generated when starting the flow; mismatches return `403 authorization_code_missing_state`. type: string required: - code - state type: object RestExceptionResponse: description: Represents the API error response properties: code: description: Specific error code for this error type, documented per endpoint type: string http_status_code: description: HTTP status code that was returned with this error, useful if client get response code format: int32 type: integer message: description: User readable English description of the error type: string parameters: additionalProperties: description: Attributes related to the error, varies be error code, documented per endpoint type: object description: Attributes related to the error, varies be error code, documented per endpoint type: object unique_id: description: Unique id associated with this error, useful for discussions with Extole type: string required: - code - http_status_code - message - parameters - unique_id type: object SuccessResponse: properties: status: type: string required: - status type: object ZonedDateTime: description: '[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) or [RFC 9557](https://datatracker.ietf.org/doc/html/rfc9557#section-4) date-time with a numeric [UTC offset](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and an optional [IANA time-zone](https://datatracker.ietf.org/doc/html/rfc9557#section-4) suffix in square brackets. Precision up to milliseconds.' example: '2025-10-24T02:00:00-07:00' pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])(\[[^\]]+\])?$ type: string securitySchemes: COOKIE: in: cookie name: extole_token type: apiKey HEADER: in: header name: Authorization type: apiKey x-bearer-format: bearer QUERY: in: query name: access_token type: apiKey x-tagGroups: - name: Integration API - Consumer to Extole tags: - Authentication - Content - Email - Events - Persons - Profile Assets - Profiles