As a Technical Account Manager, I spend a lot of time helping customers architect solutions for complex identity environments. One request comes up constantly: “I have a valid token from somewhere else ( a legacy system, a partner, or an internal microservice) and I need to trade it for an Auth0 token to access my API.”
Historically, solving this meant building an ‘intermediary’ service to validate the external token and then performing a Client Credentials exchange. While valid, this pattern requires additional maintenance and often loses the original user context.
Enter Custom Token Exchange.
Leveraging the IETF RFC 8693 standard, Auth0 allows you to implement native token exchange patterns directly within the platform using Auth0 Actions. This feature is a game-changer for migration scenarios, microservices architectures, and federated setups.
In this post, I’ll walk you through what Custom Token Exchange is, why you should use it, and how to implement it securely.
What is Custom Token Exchange?
At its core, Token Exchange is a simple concept: you send a Subject Token (the token you have) to an authorization server, and if valid, it returns a Requested Token (the token you need).
In Auth0, this allows your applications to send an arbitrary token (like a legacy session ID, a third-party JWT, or an opaque token) to Auth0’s /oauth/token endpoint. Auth0 then triggers a specific Action where you define the logic to validate that token and issue a new Auth0 Access Token in return.
Key Components
To make this work, Auth0 utilizes two main components:
-
Token Exchange Profiles: A configuration that links a specific subject_token_type (e.g., urn:ietf:params:oauth:token-type:legacy-token) to a specific Auth0 Action.
-
custom-token-exchange Action Trigger: A specific Action trigger where you write the Node.js code to validate the incoming token and define the claims for the new token.
Real-World Use Cases
Why would you need this? Here are the three most common scenarios I see in the field:
1. Phased Migrations (The “Strangler Fig” Pattern)
You are migrating from a legacy identity provider to Auth0. Instead of a “big bang” migration where all apps must switch at once, you can use Token Exchange.
-
Scenario: App A still uses the Legacy IdP. App B has moved to Auth0.
-
Flow: When App A needs to call an API protected by Auth0, it exchanges its Legacy IdP token for an Auth0 Access Token.
-
Benefit: You can migrate applications one by one without breaking communication between them.
2. Microservices & On-Behalf-Of Flow
You have a chain of services (Service A calling Service B).
-
Scenario: A user logs into Service A. Service A needs to call Service B, but Service B requires a token with different scopes or a different audience.
-
Flow: Service A exchanges the user’s original Access Token for a new token specifically scoped for Service B.
-
Benefit: Keeps your architecture secure by adhering to the Principle of Least Privilege. Service B receives a token meant only for it, rather than a broad token meant for the frontend.
3. B2B Federation with Proprietary Tokens
You have a partner who wants to embed your application, but they don’t use standard OIDC/SAML.
-
Scenario: The partner sends you a proprietary signed JWT or an API key.
-
Flow: You configure a Token Exchange Profile to accept their specific token type, validate their signature in an Action, and issue an Auth0 token for your app.
Summary
Custom Token Exchange bridges the gap between the “perfect” OAuth world and the messy reality of enterprise architecture. Whether you are decoupling a monolith, migrating from a legacy system, or integrating with a partner, it allows you to centralize your authorization logic in Auth0 without rewriting your entire application stack.
Ready to try it out? Check the Auth0 Actions Documentation to get started.