Set Up Standard Account Linking

Standard account linking connects a shopper’s agent platform session, such as Gemini, to their account on your site. The shopper signs in to your merchant platform, or creates an account, through Auth0’s Universal Login, and approves the access the agent requests. Auth0 then issues the agent platform an access token for that shopper. The agent shows a consent screen built from your UCP scopes before it sends the shopper to your Auth0 tenant. Standard account linking uses the authorization code flow and supports both public and confidential clients. Public clients use the authorization code flow with PKCE, and confidential clients authenticate with their client credentials. No UCP-specific token endpoint behavior is required.

Prerequisites

Configure your UCP resource server and add your UCP scopes.
Set your UCP resource server as the tenant default audience.
Create or use a connection where your shoppers’ accounts live: an Auth0 database connection or an enterprise connection to your existing identity provider. If the agent platform is a third-party application, you must promote the connection to the domain level.

Register the agent platform

Model the agent platform as an application in Auth0. It can be a first-party or a third-party application. Create it manually, or, if the agent platform supports it, through its Client ID Metadata Document (CIMD).

Navigate to Dashboard > Applications > Applications and select Create Application.
Select the application type that matches the agent platform’s client type. Choose Regular Web Application for a confidential client, or Native or Single Page Web Application for a public client. Use the redirect URI provided by the agent platform, and for a confidential client, its client credentials.
For an agent platform you don’t own, such as Gemini, create a third-party application. Toggle on This application is owned by a third party. Enable stricter security controls. In the Management API, set is_first_party to false and third_party_security_mode: strict.

If you register a third-party application, it’s subject to enhanced security controls and require additional configuration. Applications registered using CIMD are automatically third-party applications in strict mode. To learn more, read Configure Third-Party Applications.

Authorize the agent platform to call your UCP server

Create a client grant between the application and your UCP resource server, and grant the UCP scopes you want to expose.

Navigate to Dashboard > Applications > APIs and select your UCP resource server.
Select the Application Access tab.
Find the agent platform’s application, authorize it, and select the scopes to grant.

For third-party applications, shoppers approve access through the regular end-user consent prompt during Universal Login. First-party applications skip the consent prompt.

Authorization code flow

The agent platform reads your scopes_supported metadata and shows its own consent screen.
The agent platform redirects the shopper to your tenant’s /authorize endpoint with a scope parameter. Public clients also send a PKCE code challenge.
The shopper signs in or signs up through Universal Login and, for third-party applications, approves access on the consent screen.
Auth0 redirects back with an authorization code.
The agent platform exchanges the code for an access token at /oauth/token. Confidential clients authenticate with their client credentials. Public clients send the PKCE code verifier.

The shopper’s agent platform session is now linked to their account on your site, so the agent can act for that shopper when it calls your UCP server. Because the agent platform doesn’t send an audience parameter, Auth0 issues the token for your tenant default audience.

Use UCP server to call first-party APIs

If you already have an API that provides your commerce functionality, and you’re adding UCP as a new way to interact with it, model them as two separate resource servers in Auth0:

Your UCP resource server, which agent platforms call with the access token from the authorization flow.
Your existing API, which your UCP server calls on the shopper’s behalf.

Your UCP server then uses On-Behalf-Of (OBO) token exchange to exchange the shopper’s UCP access token for a token scoped to your existing API. The new token keeps the shopper as the subject, so your API sees which shopper the request is for. It also records your UCP server as the actor in the act claim.

Configure OBO token exchange

Follow the standard OBO configuration, using your UCP resource server as the incoming token’s audience:

Create a Custom API client linked to your UCP resource server. Set resource_server_identifier to your UCP resource server’s identifier.
Enable On-Behalf-Of Token Exchange on the Custom API client.
Create a user-delegated client grant between the Custom API client and your existing API, and grant the scopes your UCP server needs.

Exchange the shopper’s token

When your UCP server receives a request, validate the access token, then exchange it for a token for your existing API. Make a POST request to the /oauth/token endpoint:

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "client_id": "YOUR_CUSTOM_API_CLIENT_ID",
    "client_secret": "YOUR_CUSTOM_API_CLIENT_SECRET",
    "subject_token": "UCP_ACCESS_TOKEN",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "audience": "https://api.acme.example.com"
  }'

Set audience to your existing API’s identifier. To learn more, read Perform OBO token exchange. Cache the exchanged token until it expires instead of exchanging for every request.

Get Started

Reference

Set Up Standard Account Linking

Prerequisites

Register the agent platform

Authorize the agent platform to call your UCP server

Authorization code flow

Use UCP server to call first-party APIs

Configure OBO token exchange

Exchange the shopper’s token

Next steps

​Prerequisites

​Register the agent platform

​Authorize the agent platform to call your UCP server

​Authorization code flow

​Use UCP server to call first-party APIs

​Configure OBO token exchange

​Exchange the shopper’s token

​Next steps

Prerequisites

Register the agent platform

Authorize the agent platform to call your UCP server

Authorization code flow

Use UCP server to call first-party APIs

Configure OBO token exchange

Exchange the shopper’s token

Next steps