Skip to main content
Custom Token Exchange is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s product release cycle, read Product Release Stages. To learn more about subscription types, review the Auth0 pricing page.
Custom Token Exchange enables applications to exchange their existing tokens for Auth0 tokens when calling the /oauth/token endpoint, as defined in RFC 8693. Common use cases for the Custom Token Exchange include:
  • Getting Auth0 tokens for another
  • Integrating with an external
  • Migrating to Auth0
To learn more, read Example Use Cases and Code Samples. Each Custom Token Exchange request maps to a Custom Token Exchange Profile that is governed by an Action, where you can:
  • Write custom code to decode and validate subject_tokens passed to the /oauth/token endpoint
  • Authorize access and set the user to proceed with the transaction.
You can configure multiple Custom Token Exchange Profiles for an application. After the Auth0 Authorization Server validates that the Custom Token Exchange request is valid and maps to an existing Custom Token Exchange Profile, the Custom Token Exchange trigger executes the single Action associated with that profile. The application can then leverage the Custom Token Exchange to authenticate and get Auth0 access, ID, and refresh tokens for the user.
Custom Token Exchange gives you the added flexibility to set the user for the transaction by taking on the additional responsibility of securely validating the corresponding subject token that identifies the user for the transaction.Remember that subject tokens used with Custom Token Exchange can be any token format or type you require, 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.To learn about different options for implementing secure validation of your subject tokens, read and apply the recommendations included in Example Use Cases and Code Samples. Make sure you also take into consideration and apply Attack Protection capabilities.

​
Tenant logs

Each Custom Token Exchange transaction generates a tenant event log:
  • Successful transactions: secte logs
  • Failed transactions: fecte logs
Use the tenant logs to help you troubleshoot any issues you encounter with your token exchange.

​
Limitations

Custom Token Exchange in Early Access does not support the following:
  • MFA API methods api.authentication.challengeWith() and api.authentication.EnrollWith()
  • When a Custom Token Exchange transaction is associated with an Organization, api.multifactor.enable() and MFA policies are not supported
  • Custom DB Connections with import mode ON are not supported for setUserByConnection() operations
  • Specific delegation support (e.g. actor_token and actor claim)
  • Third-party and non-OIDC conformant clients