Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0-fix-auth-api-docs-migration-completion.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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 does not support the following:
  • MFA API methods api.authentication.challengeWith() and api.authentication.EnrollWith()
  • 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
  • The target API must have Allow Skipping User Consent enabled since consent cannot be collected in a non-interactive flow.

Example Use Cases

Learn about Custom Token Exchange example use cases with code samples for implementation.

Configure Custom Token Exchange

Learn how to configure the Custom Token Exchange by associating an Action with a Custom Token Profile.

Multi-Factor Authentication (MFA) with Custom Token Exchange

Learn how to use Multi-Factor Authentication (MFA) with Custom Token Exchange.

Attack Protection with Custom Token Exchange

Learn how to use Attack Protection with Custom Token Exchange.