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.
To configure the Custom Token Exchange for your application, you need to:

​
Prerequisites

Before configuring the Custom Token Exchange, make sure your application meets the following prerequisites:
  • Is a first-party client
  • Is OIDC-conformant
To configure your application, navigate to Applications > Advanced Settings > OAuth in the Auth0 Dashboard.

​
Enable Custom Token Exchange for your application

To enable the Custom Token Exchange, create a new application or update an existing one with the Auth0 Dashboard or the Management API. You can create multiple applications to use Custom Token Exchange. When you create a new application:
  1. By default, Custom Token Exchange is disabled. To enable Custom Token Exchange, use the Management API to make a POST call to Create a Client or a PATCH call to Update a Client. Set the allow_any_profile_of_type attribute under token_exchange to ["custom_authentication"]:
{
  "token_exchange": {
    "allow_any_profile_of_type": ["custom_authentication"]
  }
}
  1. Enable the connection you want to use with Custom Token Exchange for the application.
  2. Make sure your application is flagged as First-Party and it is configured as OIDC Conformant in Dashboard > Applications > Advanced Settings > OAuth.
Custom DBs with import mode ON are only supported for setUserById() operations.
Once you create the application, note the client_id and client_secret for later use when calling the /oauth/token endpoint.

​
Configure Custom Token Exchange Profile

Each Custom Token Exchange Profile establishes a one-to-one mapping between a subject_token_type and an Action, which contains the code logic for a specific use case. Custom Token Exchange requests sent to the /oauth/token endpoint with a specific subject_token_type value will map to the corresponding Custom Token Profile and route to the associated Action for processing. To create a Custom Token Exchange Profile, you need to:
  1. Create an Action for the profile
  2. Create the Custom Token Exchange Profile
  3. Manage the Custom Token Exchange Profile

​
Create Action for the profile

Use the Custom Token Exchange Event and API objects to write an Action that:
  • Decodes and validates the subject_token based on the subject_token_type. This will provide you with information about the user for the transaction.
  • Enforce any authorization policy you may need to apply for the transaction.
Once you are sure the transaction can proceed, set the user. Auth0 will then issue access, ID, and refresh tokens for this user as a form of user authentication. To learn from example Custom Token Exchange Actions, read Example Use Cases and Code Samples. Once you’ve written your Action, add and and deploy it in the Auth0 Dashboard.
  1. Navigate to Actions > Library.
  2. Select Create Action > Build from Scratch.
  3. In the Create Action dialog, enter a name and select the Custom Token Exchange trigger from the drop-down.
  1. Select Create.
  2. Deploy the Action.
After you deploy the Action, copy the Action ID that Auth0 has assigned to it. You still need to add your custom logic to the Action. First, get the Action ID to create the Custom Token Exchange Profile.
  1. To get the Action ID in the Auth0 Dashboard, navigate to the URL of the browser window. The Action ID should be the last part of the URL, as shown in the following image:
You can also get the Action ID via the Management API. First, get a Management API token to consume the API. Then, make the following GET request to the /actions endpoint: 
curl --location 'https://{yourDomain}/api/v2/actions/actions?actionName={yourActionName}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
You should receive the Action ID in the response body within actions[0].id. You need the Action ID to create the Custom Token Exchange Profile.

​
Create Custom Token Exchange Profile

To create the Custom Token Exchange Profile, use the Management API to make a POST request with the following parameters to the /token-exchange-profiles endpoint: 
curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "<YOUR_PROFILE_NAME>",
    "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
    "action_id": "<YOUR_ACTION_ID>",
    "type": "custom_authentication"
}'
ParameterDescription
subject_token_typeUnique profile token type URI starting with https:// or urn

The following namespaces are reserved and you can’t use them:

  • http://auth0.com
  • https://auth0.com
  • http://okta.com
  • https://okta.com
  • urn:ietf
  • urn:auth0
  • urn:okta
action_idAction ID of Action associated with the Custom Token Profile.
typeShould be set to custom_authentication.
If you’ve successfully created a Custom Token Exchange Profile, you should receive a response like the following: 
{
  "id":"tep_9xqewuejpa2RTltf",
  "name":"<YOUR_PROFILE_NAME>",
  "type":"custom_authentication",
  "subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
  "action_id":"<YOUR_ACTION_ID>",
  "created_at":"2025-01-30T13:19:00.616Z",
  "updated_at":"2025-01-30T13:19:00.616Z"
}

​
Manage Custom Token Exchange Profile

To manage your Custom Token Exchange Profile, use the Management API to make requests to the /token-exchange-profiles endpoint. To get all your Custom Token Exchange Profiles, make the following GET request to the /token-exchange-profiles endpoint. The /token-exchange-profiles endpoint supports checkpoint pagination if you have several profiles. 
curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
To update the name or the subject_token_type of an existing profile, make the following PATCH request to the /token-exchange-profiles endpoint.
Once the Action is created, you cannot modify the Action ID.
curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "external-idp-migration",
    "subject_token_type": "urn:partner0:external-idp-migration"
}'
To delete a Custom Token Exchange Profile, make the following DELETE request to the /token-exchange-profiles endpoint: 
curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data ''