Skip to main content
Privileged Worker Token Exchange with Token Vault is currently in Early Access. To learn more about Auth0’s product release cycle, read Product Release Stages. To participate in this program, contact Auth0 Support or your Technical Account Manager.
Token Vault supports the Privileged Worker Token Exchange, which enables a client application to exchange a signed JWT (subject token) for an external provider’s access token (requested token). After successful user authentication and authorization, a client application typically passes the user context, which contains the user’s identity, permissions, and session state, as an access or refresh token to perform the token exchange with Token Vault. In service-to-service flows, a client application, such as a backend application or service worker, may need to access resources on the user’s behalf, but because the “user is not present” in an interactive session, the client application doesn’t have access to the user context. In these service-to-service scenarios, the client application can generate a signed JWT bearer token and use it as the subject token to perform the token exchange and receive the necessary tokens to call external APIs. This means the client application can perform actions on the user’s behalf without an active user interaction or session. To use the Privileged Worker Token Exchange with Token Vault, the client application must be a highly privileged client that can request access tokens from external providers via Token Vault. It should authenticate with Token Vault using asymmetric cryptographic methods such as Private Key JWT assertion or mutual TLS authentication.

​
Prerequisites

Only certain types of clients can use the Privileged Worker Token Exchange with Token Vault:
  • The client must be a first-party client, i.e. the is_first_party property is true.
  • The client must be a confidential client with a valid authentication mechanism, i.e. the token_endpoint_auth_method property must not be set to none.
  • The client must be OIDC conformant, i.e. the oidc_conformant must be true.
Before configuring Privileged Worker Token Exchange for your client application:
  1. Enable the Token Vault grant type for your client application.
  2. Configure Private Key JWT or mutual TLS authentication for your client application.

​
Configure client application

To configure the client application’s privileged access to Token Vault, you need to provide a public key that will be used to verify a signed JWT as the subject token. You also need to restrict which IP addresses the client may make requests from, and pin the client to the connections and scopes it’s allowed to request — without these, the Privileged Worker Token Exchange will not work.
  1. Navigate to Applications > Applications and select your application.
  2. Select the Settings tab, scroll to the Privileged Worker section, and toggle on Enable Privileged Worker. In the modal, select an existing public key credential or upload a new one, then select Save.
  3. Once the credential is saved, enter at least one IP address or CIDR range in the IP Allowlist field.
  4. Under Permissions, select Add Permission. In the modal, select a Connection and enter the Scopes this connection is allowed to request, then select Save. Repeat for each connection you want to allow. You can configure up to 5 permissions and 20 scopes in total.
  5. Select Save Changes.
  6. For each connection referenced in Permissions, make sure it’s also enabled for this application. Navigate to Authentication > [Connection type], select the connection, go to the Applications tab, and toggle the connection on for your application.
Token Vault settings showing Enable Token Vault toggle and Credential selector
The ip_allowlist (IP Allowlist in the Dashboard) restricts which IP addresses may make Privileged Worker exchange requests. This binds the client credential to known server egress IPs, so a leaked credential cannot be used from an arbitrary IP address. Both IPv4 and IPv6 addresses and CIDR ranges are supported, with a maximum of 10 entries. The grants (Permissions in the Dashboard) pins the client to a specific set of connections and, within each connection, a specific set of scopes. A Privileged Worker token exchange request is rejected if it targets a connection not listed in grants. Additionally, requesting a narrower scope than what was granted causes Token Vault to return a token restricted to that narrower scope provided the identity provider supports downscoping, otherwise the request fails rather than silently returning the full granted scope. A maximum of 5 connections and 20 scopes (across all connections combined) can be configured. Note that the listed connection must be enabled for the client, as described above.
ip_allowlist and grants are not required to save a client’s configuration, but both must be populated for the Privileged Worker Token Exchange to work: any request from an IP not in ip_allowlist, or for a connection or scope not in grants, will be rejected.

​
Create signed JWT subject token

After configuring your client application with the public key, you need to create the subject token that will be exchanged for an access token for an external API. The subject token is a JSON Web Token (JWT) with the necessary claims. It is signed with the private key. The JWT has a standard format and claims: Header Payload The following is an example JWT:
Do not include personally identifiable information (PII) in audit_context. This value is recorded in tenant logs and may be visible to administrators and log streaming destinations.
The following code sample is a script that generates a signed JWT subject token:

​
Request token for external API

Once you have the signed JWT, you can make a request for the access token for the external API: