| name | ucp-identity-linking |
| description | Implement UCP Identity Linking — OAuth 2.0 authorization code flow for linking buyer accounts between platforms and merchants, enabling personalized checkout experiences. Use when implementing account linking or SSO for UCP.
|
UCP Identity Linking
Before writing code
Fetch live spec: Web-search site:ucp.dev specification identity-linking and fetch the page for exact OAuth requirements, scopes, and metadata format.
Also fetch https://developers.google.com/merchant/ucp/guides/identity-linking for Google's integration guide.
Conceptual Architecture
What It Enables
Identity Linking lets a Platform (AI agent) authenticate a buyer with a Business (merchant) so the agent can:
- Access the buyer's existing account (loyalty points, saved addresses, order history)
- Apply account-specific discounts or pricing
- Provide personalized checkout experiences
Protocol: OAuth 2.0 Authorization Code Flow
UCP mandates RFC 6749 Section 4.1 (Authorization Code) as the primary mechanism:
- Platform redirects buyer to Business's authorization endpoint
- Buyer authenticates and consents
- Business redirects back with authorization code
- Platform exchanges code for access token at Business's token endpoint
- Platform includes access token in subsequent UCP requests
Requirements
- HTTP Basic Authentication (RFC 7617) for client credentials at the token endpoint
- RFC 8414 OAuth Authorization Server Metadata at
/.well-known/oauth-authorization-server
- RFC 7009 token revocation support
- RFC 9728 HTTP Resource Metadata — for discovering and linking identity provider metadata
- Optional: OpenID RISC Profile 1.0 for async account status updates (e.g., account deleted)
UCP Scopes
| Scope | Grants |
|---|
ucp:scopes:checkout_session | All checkout operations (create, get, update, complete, cancel) |
A scope covering a capability grants access to ALL operations of that capability.
Capability Declaration
Identity Linking is declared as a capability in the Business's discovery profile. It includes:
- Authorization endpoint URL
- Token endpoint URL
- Supported scopes
- Client registration details
Implementation Guidance
Business:
- Implement standard OAuth 2.0 Authorization Code server
- Publish OAuth metadata at
/.well-known/oauth-authorization-server
- Map UCP scopes to internal permissions
- Issue access tokens that the Platform includes in UCP requests
Platform:
- Discover identity linking capability from Business profile
- Initiate OAuth flow when buyer wants to link their account
- Store and refresh access tokens
- Include tokens in UCP request authorization
Fetch the exact current requirements from the live spec — OAuth details (PKCE requirements, token formats, etc.) may evolve.
