> ## Documentation Index > Fetch the complete documentation index at: https://doc.extole.com/llms.txt > Use this file to discover all available pages before exploring further. # Exchange OIDC authorization code > 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. ## OpenAPI ````yaml /api-reference/management-expert.json post /v4/tokens/openid-connect/authorization-code-flow openapi: 3.0.1 info: description: >- Advanced configuration endpoints for Extole platform experts: campaign controllers, typed actions and triggers, advanced component types and facets, source mapping, report post-handlers, pre-handlers, and other expert configuration surfaces not included in the standard Management API. title: Management Expert API version: '1.0' servers: - description: Production url: https://api.extole.io security: - HEADER: [] - QUERY: [] - COOKIE: [] tags: - name: Authentication - name: Campaign Controllers - name: Campaign Controllers Actions - name: Campaign Controllers Triggers - name: Campaign Flow Steps - name: Components - name: Components Grants - name: Components Subscriptions - name: Components Types - name: Content - name: Debug - name: Domains - name: Email - name: Event Prehandlers - name: Events - name: Javascript Core Extensions - name: Persons - name: Profiles - name: Report Schedules - name: Report Types - name: Reporting - name: Security Keys - name: Settings paths: /v4/tokens/openid-connect/authorization-code-flow: post: tags: - Authentication summary: Exchange OIDC authorization code 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 components: schemas: 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 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 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 examples: 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 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 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 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 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_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 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 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 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 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 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 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 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 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 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 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 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 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_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 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 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 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 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 securitySchemes: HEADER: in: header name: Authorization type: apiKey x-bearer-format: bearer QUERY: in: query name: access_token type: apiKey COOKIE: in: cookie name: extole_token type: apiKey ````