Authenticate
Manage Users
Customize
Auth0 AI
PlatformTo use Custom Token Exchange, make aDocumentation Index
Fetch the complete documentation index at: https://auth0-feat-docs-5498.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
POST request to the /oauth/token endpoint with the following parameters:
Remember that subject and actor tokens used with Custom Token Exchange can be any token format or type, as long as your Action code can interpret them. You must implement strong validation of the tokens you receive and accept. If you fail to do so, you open yourself up to different attack vectors, such as spoofing or replay attacks, resulting in bad actors being able to authenticate with someone else’s user ID or acting on their behalf in an unauthorized manner.Each
subject_token_type maps to a Custom Token Exchange Profile and is associated with an Action that will be executed to control that transaction.| Parameter | Description |
|---|---|
grant_type | For Custom Token Exchange, use urn:ietf:params:oauth:grant-type:token-exchange. |
subject_token_type | The type of the subject token. For Custom Token Exchange, this can be any URI scoped under your own ownership, such as http://acme.com/legacy-token or urn:acme:legacy-token.The following namespaces are reserved and cannot be used:
|
subject_token | The subject token, which your action should validate and use to identify the user. |
client_id | The client ID of the application you are using for the Token Exchange. As for other grant types, you can also pass the client ID in the Authorization header using HTTP Basic Auth. |
client_secret | The client secret of the application you are using for the Token Exchange. As for other grant types, you can also pass the client secret in the Authorization header using HTTP Basic Auth. Other alternatives are also available as explained in Auth0 Authentication API reference docs. Note Custom Token Exchange can be used by public Applications. Make sure to read Attack Protection in that case. |
audience | The API identifier defined in Auth0. The default tenant audience will be used when not present, as configured in Tenant Settings. |
scope | (Optional) The OAuth2 scope parameter. |
organization | (Optional) The organization identifier you want the request to be associated with. Alternatively, you can specify an organization name if Use Organization Names in Authentication API is allowed for your tenant. To learn more about how the request is processed, read about the api.authentication.setOrganization() API method. |
actor_token | (Optional) A token identifying the actor or the principal performing delegation on behalf of the subject user. Must be provided together with actor_token_type. |
actor_token_type | (Optional) The type of the actor token. Must be provided together with actor_token. For Auth0 ID tokens, use urn:ietf:params:oauth:token-type:id_token for automatic server-side validation. For other values, follow the same namespace restrictions as subject_token_type. |
When an actor is set for the transaction, refresh tokens are not issued regardless of requested scopes. The
offline_access scope is excluded from the response. This is by design: delegated tokens should not outlive the immediate exchange, ensuring that each subsequent access request goes through the CTE Action’s authorization logic to re-validate the delegation.Your CTE Action is responsible for securely validating the actor_token by applying the same rigor (e.g., cryptographic signature verification) as you would for the subject_token. When actor_token_type is urn:ietf:params:oauth:token-type:id_token, Auth0 performs this validation automatically.event.request.body in the corresponding Action.
Sample request
Sample request with actor token
When performing a delegated authorization exchange, includeactor_token and actor_token_type: