How it works
Token Vault supports the following token exchange patterns depending on your application type.Refresh token exchange
Use the refresh token exchange when your application can obtain Auth0 refresh tokens, such as web, mobile, or native applications. This allows the agent to call external APIs even when the user is not actively using the application.
Token Vault using Refresh Tokens
1
User connects external provider
The user logs in and authorizes access to an external provider (e.g., Google) via the Connected Accounts flow. Auth0 stores the provider’s access and refresh tokens in Token Vault.
2
Agent requests external access token
When the agent needs to call the external API, it performs a refresh token exchange — passing the Auth0 refresh token to the
/oauth/token endpoint to retrieve the external provider’s access token from Token Vault.3
Token Vault returns external access token
Auth0 validates the refresh token, locates the stored external token, and returns the external provider’s access token to the agent.
4
Agent calls the external API
The agent uses the external access token to call the third-party API on the user’s behalf and returns the response to the user.
If your application uses Organizations, authenticate the user with the target organization before authorizing the external provider through Connected Accounts. Organizations determine the session context, but Token Vault still exchanges tokens for the individual signed-in user.
Access token exchange
Use the access token exchange when your application cannot obtain refresh tokens, such as Single-Page Applications (SPAs) or headless agents and CLIs. The backend API performs the token exchange using a Custom API Client linked to itself.
Token Vault using Access Tokens
1
User connects external provider
The user logs in and authorizes access to an external provider via the Connected Accounts flow. Auth0 stores the provider’s tokens in Token Vault.
2
SPA calls backend API with Auth0 access token
The SPA passes the Auth0 access token in the
Authorization header when calling the backend API. The backend validates the token’s signature, issuer, audience, expiration, and scopes.3
Backend performs access token exchange
The backend uses a Custom API Client — configured with the same identifier as the backend API — to exchange the Auth0 access token for the external provider’s access token via the
/oauth/token endpoint.4
Token Vault returns external access token
Auth0 validates the request, locates the stored external token, and returns the external provider’s access token to the backend.
5
Agent calls the external API
The backend uses the external access token to call the third-party API on the user’s behalf and returns the response to the user.
Connections
Auth0 supports popular social and enterprise external providers such as Google, GitHub, Slack, and more. Once the user logs in and authorizes access to the external provider, their account is added to Auth0 as a Token Vault connection. With Token Vault, AI agents can securely access external (third-party) APIs through authorized connections to perform tasks on the user’s behalf, such as:- Reading a user’s Google calendar to schedule a meeting.
- Accessing a user’s Microsoft documents to summarize them.
- Connecting to a CRM like Salesforce to retrieve customer information.
