Identity Linking Capability Specification

Basic Information

• Capability Name: dev.ucp.common.identity_linking
• Version: 2026-01-11
• Official Specification: identity-linking.md

Overview

The Identity Linking capability allows platforms (like Google, agent services) to obtain authorization to act on users’ behalf at business sites.

This is foundational for commerce experiences, used for:

• Accessing membership benefits
• Using personalized offers
• Managing wish lists
• Performing authenticated checkout

Technical Foundation

This specification is based on OAuth 2.0 for secure account linking.

Platform Requirements

Authentication Requirements

• MUST authenticate using client_id and client_secret via HTTP Basic Authentication (RFC 7617) for token exchange
• MAY support Client Metadata
• MAY support dynamic client registration mechanisms

Token Usage

• MUST use Bearer schema in HTTP Authorization header:

  Authorization: Bearer <access_token>

OAuth Flow

• MUST implement OAuth 2.0 Authorization Code flow (RFC 6749 4.1)
• SHOULD include unique, unguessable state parameter in authorization request to prevent CSRF (RFC 6749 10.12)

Revocation and Security Events

• SHOULD call business revocation endpoint when user initiates unlinking on platform side (RFC 7009)
• SHOULD support OpenID RISC Profile 1.0 for handling asynchronous account updates, unlinking events, and cross-account protection

Business Requirements

OAuth Implementation

• MUST implement OAuth 2.0 (RFC 6749)
• MUST comply with RFC 8414 for declaring OAuth 2.0 endpoint locations (/.well-known/oauth-authorization-server)
  • SHOULD implement RFC 9728 (HTTP Resource Metadata)
  • SHOULD populate scopes_supported
• MUST enforce client authentication at Token endpoint

Account Creation

• MUST provide account creation flow if user doesn’t already have an account

Scope Support

• MUST support standard UCP scopes (see Scopes section), granting tokens permission for all associated operations on a given resource
• MAY grant additional permissions beyond explicitly requested scopes, provided at least the requested scopes are included
• MAY define additional custom scopes

Revocation and Security Events

• MUST implement standard token revocation per RFC 7009
• MUST revoke specified token, SHOULD recursively revoke all associated tokens (e.g., revoking a refresh_token MUST also revoke all access_tokens issued from it)
• MUST support revocation requests authenticated using the same client credentials as the token endpoint
• SHOULD support OpenID RISC Profile 1.0 to enable cross-account protection

Scopes

Structure Design

Scope complexity should be hidden in the consent screen presented to users: users shouldn’t see one operation per line, but rather generic descriptions like “Allow [Platform] to manage checkout sessions.”

Resource-Operation-Scope Mapping

Rule: A scope covering a capability MUST grant access to all associated operations of that capability. For example, ucp:scopes:checkout_session MUST grant access to all: Get, Create, Update, Delete, Cancel, Complete.

Authorization Server Metadata Example

Per RFC 8414, metadata should be hosted at /.well-known/oauth-authorization-server:

{
  "issuer": "https://merchant.example.com",
  "authorization_endpoint": "https://merchant.example.com/oauth2/authorize",
  "token_endpoint": "https://merchant.example.com/oauth2/token",
  "revocation_endpoint": "https://merchant.example.com/oauth2/revoke",
  "scopes_supported": [
    "ucp:scopes:checkout_session",
  ],
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic"
  ],
  "service_documentation": "https://merchant.example.com/docs/oauth2"
}

Implementation Checklist

Platform Implementation Checklist

• Use HTTP Basic Authentication for token exchange
• Use Bearer token in API requests
• Implement Authorization Code flow
• Include unique state parameter for CSRF protection
• Support token revocation
• Support RISC Profile (optional)

Business Implementation Checklist

• Implement OAuth 2.0 server
• Provide /.well-known/oauth-authorization-server metadata
• Support ucp:scopes:checkout_session scope
• Provide account creation flow
• Implement token revocation endpoint
• Support recursive token revocation
• Support RISC Profile (optional)

Reference Links

• Official Identity Linking Specification
• OAuth 2.0 RFC 6749
• RFC 8414 - OAuth 2.0 Authorization Server Metadata
• RFC 7009 - OAuth 2.0 Token Revocation
• OpenID RISC Profile 1.0