Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0-feat-authentication-api-migration.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

  • 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
  • The subject_token_type must correspond to an existing Custom Token Exchange Profile and an associated Action.
  • For non-confidential applications that cannot keep the Client Secret safe (for example, native apps), the endpoint supports passing no Client Secret but the application itself must have the property tokenEndpointAuthMethod set to none. You can do this either from the UI (Dashboard > Applications > Application Settings) or using the Management API.
  • You have to Enable Custom Token Exchange for your application. To learn more, read the Custom Token Exchange documentation.

​
Parameters

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

​
Request Body

​
grant_type
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
​
subject_token_type
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.
​
subject_token
string
required
The subject token, which your action should validate and use to identify the user.
​
client_id
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.
​
client_secret
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.
​
audience
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.
​
resource
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.
​
scope
string
(Optional) The OAuth2 scope parameter.
​
organization
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.

​
Response

StatusDescription
200Successful response