Identity Linking

Overview

Identity Linking allows platforms and AI agents to act on behalf of users with their explicit consent. Built on OAuth 2.0, it enables personalized experiences like saved addresses, loyalty rewards, and payment methods.

OAuth 2.0 Flow

UCP uses the standard OAuth 2.0 Authorization Code flow with PKCE for enhanced security.

1. Authorization Request

GET /oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://platform.com/callback
  &response_type=code
  &scope=checkout orders loyalty
  &state=random_state_value
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256

2. User Authorization

User is redirected to the business's authorization page where they review and approve the requested scopes.

3. Authorization Callback

GET https://platform.com/callback
  ?code=AUTHORIZATION_CODE
  &state=random_state_value

4. Token Exchange

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://platform.com/callback",
  "code_verifier": "ORIGINAL_VERIFIER"
}

Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "scope": "checkout orders loyalty"
}

Available Scopes

Token Refresh

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Token Revocation

POST /oauth/revoke
Content-Type: application/json

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type_hint": "access_token",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Using Access Tokens

Include the access token in the Authorization header for all API requests:

GET /checkout/sessions/sess_abc123
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

Security Best Practices

• Always use PKCE - Protects against authorization code interception
• Validate state parameter - Prevents CSRF attacks
• Store tokens securely - Never expose in client-side code
• Request minimal scopes - Only request what you need
• Handle token expiry - Implement refresh token rotation

Error Handling

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired"
}

Common Error Codes

• invalid_request - Malformed request parameters
• invalid_client - Client authentication failed
• invalid_grant - Authorization code expired or invalid
• unauthorized_client - Client not authorized for this grant type
• invalid_scope - Requested scope is invalid or unknown

Next Steps

• Learn about Order Capability for tracking purchases
• Explore Buyer Consent Extension for GDPR compliance
• See Platform Integration for implementation examples