Skip to main content

​
Identity Linking

​
3.1 Capability Identifier

The identity linking namespace is dev.ucp.common.identity_linking. It is a cross-domain common capability (common rather than shopping) because identity linking is not limited to shopping scenarios.

​
3.2 Why Identity Linking Is Needed

Consumers may already have accounts with merchants (membership tiers, loyalty points, saved addresses, order history, payment methods). Identity linking allows AI agents to securely represent consumers and leverage this existing information to deliver a personalized shopping experience — without requiring consumers to re-enter any information or share passwords. Checkout without identity linking: The AI agent can only create a guest checkout. The consumer must manually provide all information. Checkout with identity linking: The AI agent can directly access the consumer’s saved addresses, payment methods, and membership benefits, completing the checkout in a single step.

​
3.3 Authorization Server Discovery

UCP requires merchants to publish authorization server metadata at the standard /.well-known/oauth-authorization-server endpoint (per RFC 8414): 
{
  "issuer": "https://store.example.com",
  "authorization_endpoint": "https://store.example.com/oauth/authorize",
  "token_endpoint": "https://store.example.com/oauth/token",
  "revocation_endpoint": "https://store.example.com/oauth/revoke",
  "scopes_supported": [
    "ucp:scopes:checkout_session",
    "openid",
    "profile"
  ],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"]
}
An AI agent can issue a GET request to this endpoint to automatically discover the merchant’s OAuth configuration, with no need to hard-code any authorization URLs.

​
3.4 OAuth 2.0 Authorization Code Flow

UCP uses the standard OAuth 2.0 Authorization Code flow and mandates PKCE (Proof Key for Code Exchange) for enhanced security:

​
Step 1: Generate PKCE Parameters

code_verifier = randomly generated 43-128 character string
code_challenge = BASE64URL(SHA256(code_verifier))

​
Step 2: Initiate Authorization Request

GET https://store.example.com/oauth/authorize?
  response_type=code&
  client_id=agent_shopping_001&
  redirect_uri=https://agent.example.com/callback&
  scope=ucp:scopes:checkout_session&
  state=random_csrf_token_xyz&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256
Key parameter descriptions:
ParameterDescription
scopeThe standard UCP scope is ucp:scopes:checkout_session, authorizing the AI agent to manage checkout sessions
stateCSRF protection token; must be an unpredictable random value
code_challengePKCE challenge value, preventing authorization code interception attacks
code_challenge_methodFixed as S256 (SHA-256 hash)

​
Step 3: User Authorization

The merchant presents an authorization page that clearly informs the user:
  • Which AI agent is requesting authorization
  • What permissions are being requested
  • The user can revoke access at any time
After the user confirms, the merchant redirects the browser to the redirect_uri with an authorization code: 
https://agent.example.com/callback?code=auth_code_abc123&state=random_csrf_token_xyz

​
Step 4: Token Exchange

POST https://store.example.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=auth_code_abc123&
redirect_uri=https://agent.example.com/callback&
client_id=agent_shopping_001&
client_secret=secret_xxx&
code_verifier=original_code_verifier_value

​
Step 5: Receive Tokens

{
  "access_token": "at_ucp_xxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_ucp_xxxxxxxxxxxxx",
  "scope": "ucp:scopes:checkout_session"
}

​
3.5 UCP Scope Specification

UCP defines standardized scope naming with the ucp:scopes: prefix:
ScopePermitted Operations
ucp:scopes:checkout_sessionCreate and manage checkout sessions (core scope)
Merchants may extend with custom scopes beyond UCP’s standard scopes. However, AI agents should always follow the principle of least privilege — only requesting the scopes they actually need.

​
3.6 Token Revocation (RFC 7009)

UCP requires merchants to implement a token revocation endpoint in compliance with the RFC 7009 OAuth 2.0 Token Revocation standard: 
POST https://store.example.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=at_ucp_xxxxxxxxxxxxx&
token_type_hint=access_token&
client_id=agent_shopping_001&
client_secret=secret_xxx
Revocation scenarios include:
  • User-initiated revocation: The user revokes AI agent authorization in the merchant’s account settings
  • Agent-initiated revocation: The AI agent proactively revokes the token when access is no longer needed
  • Security incident: Emergency revocation of all tokens upon detecting anomalous activity
When revoking an access_token, the associated refresh_token should also be invalidated.

​
3.7 Token Refresh

After an access_token expires, use the refresh_token to obtain a new access_token: 
POST https://store.example.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=rt_ucp_xxxxxxxxxxxxx&
client_id=agent_shopping_001&
client_secret=secret_xxx
The response includes a new access_token and potentially a new refresh_token (token rotation).

​
3.8 Security Requirements

RequirementDescription
PKCE requiredAll Authorization Code flows must use PKCE (S256)
HTTPS requiredAll OAuth endpoints must be served over HTTPS
state parameterMust use unpredictable random values to prevent CSRF
Least privilegeAI agents should only request scopes they actually need
Secure token storageaccess_token and refresh_token must be stored securely; never logged in plaintext
Strict redirect URI matchingredirect_uri must exactly match the registered value
Next chapter: Order Management — Line item status, fulfillment events, adjustments, and webhook signatures