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:

Parameter	Description
`scope`	The standard UCP scope is `ucp:scopes:checkout_session`, authorizing the AI agent to manage checkout sessions
`state`	CSRF protection token; must be an unpredictable random value
`code_challenge`	PKCE challenge value, preventing authorization code interception attacks
`code_challenge_method`	Fixed 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:

Scope	Permitted Operations
`ucp:scopes:checkout_session`	Create 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

Requirement	Description
PKCE required	All Authorization Code flows must use PKCE (S256)
HTTPS required	All OAuth endpoints must be served over HTTPS
state parameter	Must use unpredictable random values to prevent CSRF
Least privilege	AI agents should only request scopes they actually need
Secure token storage	access_token and refresh_token must be stored securely; never logged in plaintext
Strict redirect URI matching	redirect_uri must exactly match the registered value

Next chapter: Order Management — Line item status, fulfillment events, adjustments, and webhook signatures

UCP checkout API and state machine UCP order management and fulfillment events

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

UCP identity linking with OAuth 2.0

Identity Linking

3.1 Capability Identifier

3.2 Why Identity Linking Is Needed

3.3 Authorization Server Discovery

3.4 OAuth 2.0 Authorization Code Flow

Step 1: Generate PKCE Parameters

Step 2: Initiate Authorization Request

Step 3: User Authorization

Step 4: Token Exchange

Step 5: Receive Tokens

3.5 UCP Scope Specification

3.6 Token Revocation (RFC 7009)

3.7 Token Refresh

3.8 Security Requirements

​Identity Linking

​3.1 Capability Identifier

​3.2 Why Identity Linking Is Needed

​3.3 Authorization Server Discovery

​3.4 OAuth 2.0 Authorization Code Flow

​Step 1: Generate PKCE Parameters

​Step 2: Initiate Authorization Request

​Step 3: User Authorization

​Step 4: Token Exchange

​Step 5: Receive Tokens

​3.5 UCP Scope Specification

​3.6 Token Revocation (RFC 7009)

​3.7 Token Refresh

​3.8 Security Requirements

Identity Linking

3.1 Capability Identifier

3.2 Why Identity Linking Is Needed

3.3 Authorization Server Discovery

3.4 OAuth 2.0 Authorization Code Flow

Step 1: Generate PKCE Parameters

Step 2: Initiate Authorization Request

Step 3: User Authorization

Step 4: Token Exchange

Step 5: Receive Tokens

3.5 UCP Scope Specification

3.6 Token Revocation (RFC 7009)

3.7 Token Refresh

3.8 Security Requirements