Identity Linking - OAuth 2.0

To enable seamless user sessions (e.g., accessing loyalty benefits, personalized offers) and authenticated checkouts, you must implement the Identity Linking capability using OAuth 2.0. If you do not implement identity linking, you must support guest experiences.

Consult with your legal team on any questions regarding privacy regulations and consent practices.

Core Requirements

Identity linking uses OAuth 2.0 to link user accounts. Your OAuth 2.0 implementation must meet the requirements documented in OAuth Linking.

Additionally, to align with Universal Commerce Protocol (UCP) security best practices, we highly recommend implementing Proof Key for Code Exchange (PKCE) using S256 for all authorization code exchanges, and utilizing asymmetric client authentication (such as private_key_jwt or tls_client_auth) at your Token Endpoint.

Read more here: UCP General Guidelines.

Scopes

You must implement the following scopes, which grant permission for all checkout lifecycle operations (Create, Update, Complete) and for reading order data.

  • dev.ucp.shopping.order:read
  • dev.ucp.shopping.checkout:manage

User Experience: You should present requested scopes as a single, bundled consent screen (e.g., "Allow Google to manage your checkout sessions") rather than granular technical toggles.

Token usage

When a user has linked their account, Google includes the user's access token in the Authorization HTTP header for all checkout lifecycle operations (Create, Update, Complete) and order data requests:

Authorization: Bearer <access_token>

This is the same header used for machine-to-machine authentication.

Error handling

When a user-authenticated operation fails due to an identity issue, you must return a WWW-Authenticate: Bearer challenge header per RFC 6750 along with the appropriate HTTP status code and UCP error message.

identity_required

Return this error when an operation requires user identity, but the request lacks a token, or the provided token is invalid or expired.

  • HTTP Status: 401 Unauthorized
  • UCP Error Code: identity_required
  • WWW-Authenticate: Include realm="<your-issuer-uri>". If a token was present but invalid/expired, also include error="invalid_token".

insufficient_scope

Return this error when the request has a valid user identity token, but the token lacks the required scope(s) for the operation.

  • HTTP Status: 403 Forbidden
  • UCP Error Code: insufficient_scope
  • WWW-Authenticate: Include realm="<your-issuer-uri>", error="insufficient_scope", and scope="<space-separated list of required scopes>".

Advertising identity linking

You must declare the Identity Linking capability in your UCP profile. For an example of how to list this capability, see UCP profile.

Google Streamlined Linking

Google Streamlined Linking is an optional addition to standard OAuth 2.0. It leverages JWT assertions to combine intent checks and token exchange on the OAuth 2.0 token endpoint (check, create, get intents).

Google Streamlined Linking is recommended for a seamless user experience. It allows users to link accounts or create new accounts using their Google profile without leaving the Google interface. Because the flow occurs entirely within Google's UI, a linking frontend is not required. This reduces development overhead, eliminates browser redirects, and can increase conversion rates.

Authorization Server Metadata (JSON Example)

You must publish your authorization server metadata at https://[your-domain]/.well-known/oauth-authorization-server.

The following is an example of what this might look like:

{
  "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": [
    "dev.ucp.shopping.order:read",
    "dev.ucp.shopping.checkout:manage"
  ],
  "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"
}
Previous
Cart API
Next
Order lifecycle