Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0-docs-update-privilege-worker-ea-rollout.mintlify.app/llms.txt

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

Privileged Worker Token Exchange with Token Vault is currently in Beta. 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 or refresh 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 also request refresh 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. Similar to configuring JAR, you can set the Token Vault privileged access public key when creating a new client: 
POST https://{yourDomain}.auth0.com/api/v2/clients
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
{
  "name": "My App using JAR",
   “grant_types”: [“urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token”],
     “oidc_conformant”: true,
           “is_first_party”: true,
           “jwt_configuration”: {
             “alg”: 'RS256',
           },

  "token_vault_privileged_access": {
"credentials": [{
        "name": "My credential for Token Vault Privileged Access",
        "credential_type": "public_key",
        "pem": "<YOUR PEM FILE CONTENT>",
        "alg": "RS256"
}]
  },
}
You can also update an existing client with the Token Vault privileged access public key: 
PATCH https://{yourDomain}.auth0.com/api/v2/clients/{yourClientId}
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
{
  "token_vault_privileged_access": {
    "credentials": [{"id": "<YOUR_CREDENTIAL_ID>"}]
  }
}
If you need to look up the credential id, retrieve it with a GET request: 
GET https://{yourDomain}.auth0.com/api/v2/clients/{yourClientId}
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
The token_vault_privileged_access.credentials[].id field in the response contains the credential ID.

​
Configure IP allowlist

To restrict which IP addresses may make Privileged Worker exchange requests, configure an ip_allowlist on your client. 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. 
PATCH https://{yourDomain}.auth0.com/api/v2/clients/{yourClientId}
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
{
  "token_vault_privileged_access": {
    "credentials": [{"id": "<YOUR_CREDENTIAL_ID>"}],
    "ip_allowlist": ["<YOUR_SERVER_IP_ADDRESS>"]
  }
}
Once you set an ip_allowlist, any Privileged Worker token exchange request from an IP not in the list is rejected with access_denied. Requests from a client with no ip_allowlist configured are allowed from any IP.

​
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, where:
  • Header’s typ is token-vault-req+jwt
  • Header’s kid is optional if you have only one public key configured
  • Payload’s sub is the user ID for whom you want to get the token for
  • Payload’s aud is your tenant host
  • Payload’s iss is your client ID making the request
  • Payload’s jti is a unique identifier for this JWT (UUID v4 recommended) — required for replay protection
  • Payload’s audit_context is a human-readable string (1–256 characters) describing the business reason for this privileged access — required for audit trail purposes
The following is an example JWT: 
{
    alg: "RS256"  
    typ: "token-vault-req+jwt"
}
.
{
    sub: "auth0|000012030101231",
    aud: "https://{yourDomain}.auth0.com/",
    iss: "<YOUR_CLIENT_ID>",
    iat: 1758799540,
    exp: 1758800540,
    nbf: 1758799540,
    jti: "<UNIQUE_JWT_ID>",
    audit_context: "<REASON_FOR_ACCESS>"
}
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: 
import * as jwt from ‘jsonwebtoken’;
import { v4 as uuidv4 } from ‘uuid’;

const privateKey = ‘-----BEGIN RSA PRIVATE KEY-----........’;
const subjectToken = jwt.sign(
  {
    iss: CLIENT_ID,
    aud: ‘https://’ + TENANT_DOMAIN + ‘/’,
    sub: USER_ID,
    jti: uuidv4(),
    audit_context: ‘Automated nightly sync for compliance report’,
  },
  privateKey,
  {
    algorithm: ‘RS256’,
    header: {
      typ: ‘token-vault-req+jwt’,
    },
  }
);

​
Request token for external API

Once you have the signed JWT, you can make a request for the access token for the external API: 
curl --request POST 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_SIGNED_JWT_BEARER>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "requested_token_type": "http://auth0.com/oauth/token-type/token-vault-access-token",
  "connection": "google-oauth2"
}'
ParameterDescription
grant_typeThe grant type. For Token Vault, set to urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token
client_idClient application ID
client_secretClient secret. Note: For Privileged Worker Token Exchange, we recommend using Private Key JWT or mTLS authentication.
subject_token_typeType of subject token. For Privileged Worker Token Exchange, set to JWT: urn:ietf:params:oauth:token-type:jwt
subject_tokenThe signed JWT bearer token that the Auth0 Authorization Server validates to identify the user.
requested_token_typeThe requested token type. For Privileged Worker Token Exchange, you can request an access or refresh token.
connectionThe connection name, in this case, google-oauth2.