Skip to main content
Custom Token Exchange (CTE) 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.
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. If the Action successfully completes and sets a user for the transaction, post-login Actions and the rest of the Auth0 pipeline are then executed for that logged-in user.
Actions in this flow are blocking (synchronous), which means they execute as part of a trigger’s process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.

​
Custom Token Exchange vs Post Login Actions

The Post Login Actions trigger executes after the Custom Token Exchange Action runs for the user you set for the transaction. For other use cases, such as adding custom claims to access tokens, use the Post Login Action trigger. The Custom Token Exchange uses the token exchange grant type, where the event.transaction.protocol is set to oauth2-token-exchange in the Post Login Action trigger. Both the Custom Token Exchange and Native Social Login use the token exchange grant type. To distinguish between the two, use the value of the subject_token_type, which should correspond to one of your Custom Token Exchange Profiles.
Custom Token Exchange Early Access doesn’t support api.authentication.challengeWith() or api.authentication.enrollWith(). If you use those methods with your Post-Login Actions, the transaction will fail with a non-recoverable error. Make sure you skip those two methods when event.transaction.protocol==oauth2-token-exchange depending on the subject_token_type value.

​
Triggers

​
Custom Token Exchange

The custom-token-exchange trigger is the first step in the Auth0 pipeline. This function is executed after the received Custom Token Exchange request has been validated and successfully mapped to an existing profile.

​
References

  • Event object: Provides contextual information about the a Token Exchange request, including the subject_token, IP address, client, and more.
  • API object: Provides methods to use with your Token Exchange Action that allows you to set the user, reject the transaction, set user metadata and access the Actions cache, and more.

​
Common Use Cases

To learn about common Custom Token Exchange use cases, read Example Use Cases.