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 don't 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](https://developers.google.com/identity/account-linking/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](https://ucp.dev/2026-04-08/specification/identity-linking/#general-guidelines).

> [!NOTE]
> **Note:** Outbound Google Account Linking requests to your OAuth 2.0 token endpoint originate from `AS15169` and `AS396982`, send `User-Agent: OpenAuth` or `Google-AccountLinking-Fetcher/1.0`, and don't include the `UCP-Agent` header. Your firewall, rate limiter, and bot management rules must allow these requests. See [Network and WAF configuration](https://developers.google.com/merchant/ucp/guides/overview/network-and-waf#account-linking-traffic).

## 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`

> [!NOTE]
> **Note:** 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](https://developers.google.com/merchant/ucp/guides/overview/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 isn't required. This reduces development
overhead, eliminates browser redirects, and can increase conversion rates.

- **Specification:** Implementation must follow the [Requirements for
  Streamlined Linking](https://developers.google.com/identity/account-linking/oauth-with-sign-in-linking#requirements_for_streamlined_linking).
- **Standards:** While it draws concepts from [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523), it differs to enhance security.

## Authorization Server Metadata (JSON Example)

You must publish your authorization server metadata at:

    GET 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"
    }