Skip to main content

​
Endpoint

POST /oauth/token Custom Token Exchange (CTE) provides a mechanism for applications to exchange pre-existing identity tokens for Auth0 tokens by invoking the /oauth/token endpoint, adhering to the specifications of RFC 8693. This functionality is instrumental in addressing advanced integration requirements, such as exchanging existing Auth0 tokens to access another audience on behalf of the same user, facilitating the integration of external identity providers, or enabling seamless user migration into the Auth0 platform. The exchange process is fully governable, as developers can control its details using their custom logic running in a dedicated Auth0 Action for the associated use case.
Custom Token Exchange is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. It is your responsibility to securely validate the user’s subject_token. See the User Guide for more details.

​
Remarks

Read Custom Token Exchange to understand Custom Token Exchange Profiles, how a profile maps to an Action, and how to enable this flow for your application.
  • The scopes issued to the application may differ from the scopes requested. In this case, a scope parameter will be included in the response JSON. Scopes are filtered out as explained in API Access Policies for Applications.
  • MFA is not compatible with transactions where an actor is set via setActor(). In those cases, the request returns a 400 error: MFA is not supported using actor_token with the requested token exchange profile.
  • When the Action calls setActor(), issued access tokens and ID tokens include an act claim representing the delegation chain. The act claim is also included in the userinfo response.
  • To request a Session Transfer Token instead of an access token, set audience to urn:YOUR_AUTH0_TENANT_DOMAIN:session_transfer. Calling setActor() is required for this request. Read Session Delegation to learn how to redeem the resulting token to establish a session on behalf of the subject user.
  • To include standard claims (such as email) in the issued token(s), the corresponding scope (email) must be included in the request, even if your Action sets the claim explicitly. Read OpenID Connect Scopes: Standard claims to learn more.

​
Headers

​
string
A DPoP proof for the request. This is optional and only required if your application uses Demonstrating Proof-of-Possession.
​
string
End-user IP as a string value. Set this if you want Suspicious IP Throttling protection to work in server-side scenarios.

​
Body Parameters

The request body is in application/x-www-form-urlencoded format.
​
string
required
Denotes the flow you are using. For Custom Token Exchange, use urn:ietf:params:oauth:grant-type:token-exchange.Allowed values: urn:ietf:params:oauth:grant-type:token-exchange
​
string
required
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: http://auth0.com, https://auth0.com, http://okta.com, https://okta.com, urn:ietf, urn:auth0, urn:okta.
​
string
required
The subject token, which your action should validate and use to identify the user.
​
string
required
Your application’s Client ID. As for other grant types, you can also pass the client ID in the Authorization header using HTTP Basic Auth.
​
string
(Optional) Your application’s Client Secret. 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. Because Custom Token Exchange can be used by public applications, read Attack Protection to implement additional security.
​
string
(Optional) The unique identifier of the target API you want to access. The default tenant audience will be used when not present, as configured in Tenant Settings. To request a Session Transfer Token for delegated session establishment instead of an access token, use urn:YOUR_AUTH0_TENANT_DOMAIN:session_transfer.
​
string
(Optional) The identifier of the target API (resource server) you want to access. Must match an API Identifier registered in your Auth0 tenant. Used as an alternative to audience when the tenant’s Resource Parameter Compatibility Profile is set to compatibility.
​
string
(Optional) The OAuth2 scope parameter.
​
string
(Optional) The organization or identifier with which you want the request to be associated. Alternatively, you can specify an organization name if Use Organization Names in Authentication API is specified.
​
string
(Optional) A token identifying the actor performing delegation on behalf of the subject user. Must be provided together with actor_token_type. When present, refresh tokens will not be issued.
​
string
(Optional) The type of the actor token. Must be provided together with actor_token. For Auth0 ID tokens, use urn:ietf:params:oauth:token-type:id_token for automatic server-side validation (signature, expiry, issuer, user lookup). For other values, follow the same namespace restrictions as subject_token_type.

​
Response Schema

​
Response Messages