4. Select **Create**.
5. **Deploy** the Action.
When you deploy the Action, Auth0 assigns it an Action ID. You still need to add your custom logic to the Action, but first, get the Action ID to create the Custom Token Exchange Profile.
6. 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](/docs/secure/tokens/access-tokens/management-api-access-tokens#get-management-api-tokens) to consume the API. Then, make the following GET request to the `/actions` endpoint:
```bash lines
curl --location 'https://{{YOUR _TENANT}}/api/v2/actions/actions?actionName={{ACTION_NAME}}' \
--header 'Authorization: Bearer {{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 the 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:
```bash lines
curl --location 'https://{{YOUR _TENANT}}/api/v2/token-exchange-profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
--data '{
"name": "{{PROFILE_NAME}}",
"subject_token_type": "{{UNIQUE_PROFILE_TOKEN_TYPE_URI}}",
"action_id": "{{ACTION_ID}}",
"type": "custom_authentication"
}'
```
| Parameter | Description |
|---|---|
subject\_token\_type |
Unique profile token type URI starting with `https://` or urnThe following namespaces are reserved and you can’t use them:
|
action\_id |
Action ID of Action associated with the Custom Token Profile. |
type |
Should be set to custom\_authentication. |
| Parameter | Description |
|---|---|
user\_id |
The user ID, such as auth0\|55562040asf0aef. |
| Parameter | Description |
|---|---|
connection\_name |
The name of the connection where the user profile will be set. Limited to 512 characters. |
user\_profile |
An object containing the user profile attributes to be set. Limited to 24 properties. |
options |
An object specifying update and creation behavior.\{updateBehavior: 'replace' | 'none',creationBehavior: 'create\_if\_not\_exists' | 'none',}If the user exists, updateBahaviour does the following:
|
| Parameters | Description |
|---|---|
name |
String. The name of the metadata property. |
value |
String, object or array. The name of the metadata property. |
| Parameters | Description |
|---|---|
name |
String. The name of the metadata property. |
value |
String, object or array. The name of the metadata property. |
| Parameter | Description |
|---|---|
code |
A string returned in the error property in the response. Two standard error codes can be used:
If you use your own error code, it returns a 400 status code. |
reason |
A string returned in the error\_description property in the response. |
| Parameter | Description |
|---|---|
reason |
A string returned in the error\_description property in the response |
| Parameter | Description |
|---|---|
key |
String. The key of the record stored in the cache. |
| Parameter | Description |
|---|---|
key |
String. The key of the record stored in the cache. |
| Parameter | Description |
|---|---|
key |
String. The key of the record stored in the cache. |
value |
String. The value of the record to be stored. |
options |
Optional object. Options for adjusting cache behavior. |
options.expires\_at |
Optional number. The absolute expiry time in milliseconds since the unix epoch. While cached records may be evicted earlier, they will never remain beyond the supplied expires\_at.Note: This value should not be supplied if a value was also provided for ttl. If both options are supplied, the earlier expiry of the two will be used. |
options.ttl |
Optional number. The time-to-live value of this cache entry in milliseconds. While cached values may be evicted earlier, they will never remain beyond the supplied ttl.Note: This value should not be supplied if a value was also provided for expires\_at. If both options are supplied, the earlier expiry of the two will be used. |
| Property | Type | Example |
|---|---|---|
| client | ||
client\_id |
string | HOVc2PDFTH7eahimN4yNCo8mOtjfNjLV |
name |
string | My Web App |
metadata |
object | \{“foo”: “bar” } |
| tenant | ||
id |
string | dev\_1234 |
| request | ||
geoip |
object | \{ … geoip object} |
hostname |
string | dev\_1234.us.auth0.com |
ip |
string | 123.42.42.34 |
user\_agent |
string | Mozilla/5.0 |
language |
string | en |
body |
object | \{ // raw req.body } |
method |
string | POST |
| transaction | ||
subject\_token\_type |
string | urn://cic-migration-token |
subject\_token |
string | 41598922a1745f7af70 |
requested\_scopes |
string\[] | \[“openid”, “email”] |
| resource\_server | ||
id |
string | [http://acme-api/v1/profile](http://acme-api/v1/profile) |
## Call Token Exchange
To use Custom Token Exchange, make a `POST` request to the `/oauth/token` endpoint with the following parameters. Remember that:
* `subject_tokens` used with Custom Token Exchange can be any token format or type, as long as your Action code can interpret them.
* Each `subject_token_type` maps to a specific Custom Token Exchange Profile and is associated with a specific Action that will be executed to control that transaction.
| Parameter | Description |
|---|---|
grant\_type |
For Custom Token Exchange, use urn:ietf:params:oauth:grant-type:token-exchange. |
subject\_token\_type |
The type of the subject token. For Custom Token Exchange, this can be any URI scoped under your own ownership, such as `http://acme.com/legacy-token` or urn:acme:legacy-token.The following namespaces are reserved and cannot be used:
|
subject\_token |
The subject token, which your action should validate and use to identify the user. |
client\_id |
The client ID of the application you are using for the Token Exchange. As for other grant types, you can also pass the client ID in the Authorization header using HTTP Basic Auth. |
client\_secret |
The client secret of the application you are using for the Token Exchange. As for other grant types, you can also pass the client secret in the Authorization header using HTTP Basic Auth. Other alternatives are also available as explained in Auth0 Authentication API reference docs. Note Custom Token Exchange can be used by public Applications. Make sure to read Attack Protection in that case. |
audience |
The API identifier defined in Auth0. |
scope |
The OAuth2 scope parameter. |
You can configure a custom threshold and throttling rate for Custom Token Exchange with the Management API.
First, [get a Management API token](/docs/secure/tokens/access-tokens/management-api-access-tokens#get-management-api-tokens) to consume the API. Then, send the following GET request to the [Get Suspicious IP Throttling settings endpoint](https://auth0.com/docs/api/management/v2/attack-protection/get-suspicious-ip-throttling):
```bash lines
curl --location 'https://{{YOUR _TENANT}}/api/v2/attack-protection/suspicious-ip-throttling' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
```
You will receive a response like the following:
```json lines
{
"enabled": true,
"shields": [
"admin_notification",
"block"
],
"allowlist": [],
"stage": {
"pre-login": {
"max_attempts": 100,
"rate": 864000
},
"pre-user-registration": {
"max_attempts": 50,
"rate": 1200
},
"pre-custom-token-exchange": {
"max_attempts": 10,
"rate": 600000
}
}
}
```
Use the following `PATCH` request to update the `pre-custom-token-exchange` stage with the needed values. Note that the rate is the interval of time in milliseconds at which new attempts are granted.
```bash lines
curl --location --request PATCH 'https://{{YOUR _TENANT}}/api/v2//attack-protection/suspicious-ip-throttling' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{MANAGEMENT_API_TOKEN}}' \
--data '{"stage":{"pre-custom-token-exchange":{"max_attempts":10,"rate":600000}}}'
```
## Example Use Cases and Code Samples
You can use Custom Token Exchange to solve advanced integration scenarios where normal federated login strategies based on redirecting the end user cannot be applied due to technical or user experience constraints. The code provided for the use cases is incomplete and only aims at showing the logical steps you can follow with your code to address the use case. Refer to [code samples](#code-samples) for more detailed code examples.
As a prerequisite, GearUp has done a [bulk user import](/docs/manage-users/user-migration/bulk-user-imports) into their Auth0 tenant and the mobile app has a valid legacy refresh token for each user to be migrated.
1. The mobile app makes a request to Auth0 to exchange the legacy refresh token, setting it as the subject token.
2. The corresponding Custom Token Exchange profile Action executes. It validates the refresh token with the legacy IdP and gets the external user ID from the user profile. It then applies the required authorization policy and finally sets the user.
3. Auth0 responds with Auth0 access token, ID token, and refresh token.
4. The mobile app can now use the Customer APIs using Auth0 tokens without the user having to re-authenticate.
The following code sample shows how to implement this in the Custom Token Exchange Action. In this case, since user profiles were already imported into an Auth0 database connection:
* We don’t want to create the user.
* We don’t want to update the user profile.
We use the external IdP user ID to set the user in the corresponding connection.
```javascript lines expandable
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the refresh_token received in the subject_token by using it to get
// the UserProfile from the external IdP
const { isValid, user } = await getUserProfile(
event.transaction.subject_token,
event.secrets.CLIENT_SECRET,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. When we have the profile, we SET THE USER in the target connection
api.authentication.setUserByConnection(
connectionName,
{
// only the user_id in the connection is needed, as we are not
// creating nor updating the user
user_id: user.sub,
},
{
creationBehavior: "none",
updateBehavior: "none",
},
);
}
};
/**
* Exchange the refresh token and load the user profile from the legacy IdP
* @param {string} refreshToken
* @param {string} clientSecret
* @returns {Promise<{ isValid: boolean, user?: object }>} If the refresh token was exchanged successfully, returns the user profile
*/
async function getUserProfile(refreshToken, clientSecret) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
```
Read [code samples](#code-samples) for a more detailed example on how to validate opaque refresh token with the legacy IdP.
### Use Case: Re-use an external authentication provider
Another use case involves GearUp partnering with Air0, a leading travel provider, to offer their car rental services directly within the Air0 single-page application. GearUp offers a JavaScript library that encapsulates the use of their APIs. This way GearUp’s APIs can easily be consumed by Air0’s website where car rental services are being offered.
Once again, the solution needs to be invisible to end users by avoiding re-authentication to GearUp. To solve this problem, GearUp’s JavaScript library can perform a token exchange using the external Air0 ID token as the input. This results in an Auth0 access token that is generated and associated with the corresponding GearUp user based on their email address. Once the GearUp library gets the access token, it can start using GearUp’s APIs to offer car rental services directly within Air0’s website.
As a prerequisite, GearUp has set up Air0 IdP as a federated enterprise or social connection, so the user can authenticate via federate login or alternatively via Custom Token Exchange as follows:
1. The Single Page App gets the ID token from the external IdP once the user authenticates.
2. It then requests the exchanges of the ID token, setting it as the subject token.
3. The corresponding Custom Token Exchange profile Action executes. It validates the ID token and gets the user ID and other profile attributes from the token. It then applies the required authorization policy and finally sets the user.
4. Auth0 responds with Auth0 access token, ID token and refresh token.
5. The javascript code running in the SPA can now use the Customer APIs using Auth0 tokens without the user having to re-authenticate.
The following code exemplifies how to implement this in the Custom Token Exchange Action. In this case:
* We use the external IdP user ID to set the user in the corresponding connection.
* We want to create the user if they don’t yet exist.
* We don’t want to replace the user profile if a more complete set of attributes is obtained via federated login, in case the user already exists.
* We don't want to verify emails when users are created.
```javascript lines expandable
const jwksUri = "https://example.com/.well-known/jwks.json";
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the id_token received in the subject_token
const { isValid, payload } = await validateToken(
event.transaction.subject_token,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. SET THE USER in the target connection.
// We don't want to verify emails when users are created
// This example assumes subject_token (id_token) contains standard OIDC claims. Other custom mappings
// are also possible.
api.authentication.setUserByConnection(
'Enterprise-OIDC',
{
user_id: formattedUserId,
email: subject_token.email,
email_verified: subject_token.email_verified,
phone_number: subject_token.phone_number,
phone_verified: subject_token.phone_number_verified,
username: subject_token.preferred_username,
name: subject_token.name,
given_name: subject_token.given_name,
family_name: subject_token.family_name,
nickname: subject_token.nickname,
verify_email: false
},
{
creationBehavior: 'create_if_not_exists',
updateBehavior: 'none'
}
);
}
/**
* Validate the subject token
* @param {string} subjectToken
* @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
*/
async function validateToken(subjectToken) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
};
```
Read [code samples](#code-samples) for a more detailed example on how to securely validate 
The GearUp application has initially obtained an access token to consume API A on behalf of a user:
1. The app sends the request with the initial access token to API A.
2. API A backend service validates the access token and requests to exchange by setting it as the subject token for a new access token to consume API B.
3. The corresponding Custom Token Exchange profile Action executes. It validates the access token and gets the Auth0 user ID from the token. It then applies the required authorization policy and finally sets the user.
4. Auth0 responds with an Auth0 access token to consume the API B audience.
5. API A backend service calls API B using the new access token, which is still associated with the same user.
The following code exemplifies how to implement this in the Custom Token Exchange Action. In this case:
* We use the Auth0 user ID to set the user, so there is no need to set this in the scope of any connection.
* We don’t want to create or update the user.
Refer to [Validate JWTs signed with asymmetric keys](#validate-jwts-signed-with-asymmetric-keys) for expanded code samples on this use case.
```javascript lines expandable
const jwksUri = "https://example.com/.well-known/jwks.json";
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {
// 1. VALIDATE the access_token received in the subject_token
const { isValid, payload } = await validateToken(
event.transaction.subject_token,
);
if (!isValid) {
// Mark the subject token as invalid and fail the transaction.
api.access.rejectInvalidSubjectToken("Invalid subject_token");
} else {
// 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
// Use api.access.deny() to reject the transaction in those cases.
// 3. SET THE USER
api.authentication.setUserById(payload.sub);
}
/**
* Validate the subject token
* @param {string} subjectToken
* @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
*/
async function validateToken(subjectToken) {
// Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
};
```
Read [code samples](#code-samples) for a more detailed example on how to securely validate JWTs.
### Code samples
The following code samples show best practices for common scenarios for validating incoming subject tokens in a secure and performant way.
Use asymmetric algorithms and keys whenever you can as you don’t need to share any secret with Auth0. This also simplifies key rotation, such as when exposing a JWKS URI endpoint to advertise applicable public keys.