An error occurs during an On-Behalf-Of (OBO) token exchange when the client is not a Custom API client associated with a resource server. Resolving this requires configuring the Custom API client to use the same identifier as the resource server and to set the appropriate grants. Auth0 generates the following error when attempting to send a token request via OBO token exchange:

Client must be a Custom API Client with resource_server_id

• On-Behalf-Of (OBO) Token Exchange
• Custom API Clients

Only Custom API clients associated with a resource server can use the OBO token exchange. This association is completed successfully only when the client and the resource server share the same identifier.

How is the Custom API client configured for OBO token exchange?

Configure the Custom API client to share the resource server identifier, establish a user-delegated client grant, and apply the OBO token exchange grant.

1. Set app_type to resource_server and resource_server_identifier to the valid resource server to satisfy the requirements for the Custom API. Auth0 uses the resource server identifier as the audience parameter in authorization calls.
2. Choose Applications > APIs > choose the API > Settings > Access Settings and enable the Allow Skipping User Consent toggle. Custom API clients are first-party clients, and this step skips user consent for the APIs the first-party client needs to access.
3. Make a POST request to the /api/v2/clients endpoint with the following request body to create a Custom API client with the same identifier as the resource server:
   

   curl --request POST 'https://{yourDomain}/api/v2/clients' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
     --data '{
       "name": "Custom API Client",
       "app_type": "resource_server",
       "resource_server_identifier": "https://my-api.example.com"
     }'

4. Make a POST request to the /api/v2/client-grants endpoint with the following request body to create a user-delegated client grant between the Custom API client and the downstream API to authorize access:
   

   curl --location 'https://{yourDomain}/api/v2/client-grants' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
     --data '{
       "client_id": "YOUR_CLIENT_ID",
       "audience": "https://my-api.example.com",
       "scope": [
         "read:item"
       ],
       "subject_type": "user"
     }'

5. Make a PATCH request to the /api/v2/clients/{clientId} endpoint with the following request body to configure the Custom API client with the OBO token exchange grant:
   

   curl --location --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
     --data '{
       "token_exchange": {
         "allow_any_profile_of_type": ["on_behalf_of_token_exchange"]
       }
     }'

6. Make a POST request to the /oauth/token endpoint with the following request body to perform the OBO token exchange and verify the setup:
   

   curl --location 'https://YOUR_DOMAIN.us.auth0.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "subject_token": "AUTH0_SUBJECT_TOKEN",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "audience": "https://my-api.example.com"
     }'

    

    

Related References

• • On-Behalf-Of Token Exchange
  • User Consent and Third-Party Applications