Skip to main content
Custom Token Exchange allows applications to exchange an existing security token—referred to as the subject_token—for Auth0 access, ID, and refresh tokens by calling the /oauth/token endpoint, in accordance with RFC 8693.

​
How it works

The Custom Token Exchange flow is governed by a single, dedicated Custom Token Exchange Action, which is uniquely selected based on the incoming subject_token_type parameter, as configured in a Custom Token Exchange Profile.
As a prerequisite for the flow, you must define a Custom Token Exchange Profile that maps a specific subject_token_type to the Action that will handle the requests. When the Custom Token Exchange flow is triggered:
  1. The application sends a POST request to the /oauth/token endpoint with the security token to be exchanged (the subject_token) and its corresponding subject_token_type.
  2. Auth0 validates the client request and credentials.
  3. The associated Custom Token Exchange Action is executed. Your custom code must decode and validate the subject_token, enforce any necessary authorization policies, and set the user for the transaction to approve the exchange.
  4. The rest of the standard Auth0 pipeline executes to generate an Auth0 access token and optionally an ID token and refresh token for the set user.
  5. The requesting application can then use these newly issued tokens to securely call APIs on behalf of the user that was set in the Action.

​
Get started

To use Custom Token Exchange, you need to create a Custom Token Exchange Profile. The general workflow involves three main configuration steps followed by your API call:
  1. Create and deploy an Action that will contain the logic to control the token exchange. In this Action, write the custom code logic to:
    • Securely decode and validate the incoming subject_token.
    • Perform any required authorization steps for the transaction.
    • Set the corresponding user for the transaction using the available methods in the Custom Token Exchange Actions API Object.
  2. Create the Custom Token Exchange Profile in your tenant. The profile establishes a one-to-one mapping between a specific subject_token_type you will use in your requests and the Action you just created.
  3. Enable Custom Token Exchange for your application.
Once you’ve created the Custom Token Exchange Profile, you are ready to:
  1. Call your API: You can now make a POST request to the /oauth/token endpoint with the necessary parameters, including the subject_token and the subject_token_type that corresponds to your configured profile. To learn more, read Call your API using Custom Token Exchange.

​
Learn more