How to Fix "UCP Identity Linking broken"

What is UCP Identity Linking?

Identity Linking (dev.ucp.common.identity_linking) is the UCP capability that enables an AI agent platform (like Google or ChatGPT) to obtain authorization to act on behalf of a user on your store. It bridges agent-authenticated access to user-authenticated access.

Without Identity Linking, every interaction is anonymous: an agent can browse your public catalog and add items to cart, but cannot access saved addresses, wishlists, loyalty benefits, or order history. Every purchase is a "new customer" transaction.

With it working, the agent can retrieve saved shipping addresses and payment methods, apply loyalty points or member pricing, access purchase history for reordering, and complete checkout as a recognized customer. The v1 spec uses OAuth 2.0 Authorization Code flow - your store is the authorization server; the agent platform is the client.

Why this breaks AI agent experiences

When Identity Linking is broken, agents don't just get an error - they get downgraded to a worse experience:

1. Agent reads the Identity Linking capability in your manifest
2. Agent attempts to initiate the OAuth flow
3. The flow fails - metadata missing, PKCE not enforced, or scopes don't match
4. Agent falls back to anonymous access mode
5. The user's saved preferences, loyalty discounts, and address are all invisible
6. Agent presents a generic experience - or skips your store for one that recognizes the user

The worst part: this failure is silent from your perspective. Your store works fine for human shoppers and your endpoints return 200 - but agents are presenting a degraded experience to your best, repeat customers.

The 5 types of Identity Linking failures

1. Missing Identity Linking capability entirely

No Identity Linking block exists. While technically optional, missing it means you forfeit personalized commerce entirely. For stores with loyalty programs, member pricing, or repeat customers, this is functionally a failure.

2. Missing authorization server metadata

The capability is declared but points to an endpoint instead of an OAuth authorization server. The spec requires you to publish metadata at /.well-known/oauth-authorization-server so the agent can discover token endpoints, supported scopes, and auth methods. Without it, agents cannot complete the flow.

3. Scope mismatches

Your manifest declares scopes (like profile:read, orders:history) that your authorization server doesn't honor, or your server advertises a different set in scopes_supported. The agent requests scopes your server rejects, and the flow fails at the authorization step.

4. PKCE not enforced

UCP requires PKCE (code_challenge_method=S256) for all authorization code exchanges:

Authorization request: code_challenge=XXX&code_challenge_method=S256
Token request:         code_verifier=YYY
Server MUST:           validate that code_challenge == SHA256(code_verifier)
Server MUST:           reject requests without a valid code_verifier

Agents may detect missing PKCE enforcement during security validation and refuse to complete the flow, even if your server would accept the request.

5. Redirect URI mismatch

The most common cause. Your server's redirect_uris list doesn't include the redirect URI the agent platform uses. The exception: loopback redirects (targeting 127.0.0.1) match on scheme, host, and path only - ignoring the port - per RFC 8252 Section 7.3.

How to fix Identity Linking

Fix 1: Publish authorization server metadata

Create a complete metadata document at /.well-known/oauth-authorization-server:

{
  "issuer": "https://yourstore.com",
  "authorization_endpoint": "https://yourstore.com/oauth/authorize",
  "token_endpoint": "https://yourstore.com/oauth/token",
  "token_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic"],
  "scopes_supported": ["profile:read", "orders:history", "addresses:read", "loyalty:read"],
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "revocation_endpoint": "https://yourstore.com/oauth/revoke"
}

Fix 2: Align scopes between manifest and server

The scopes in your manifest's config.scopes must match your server's scopes_supported. The spec explicitly calls this out: publish scopes_supported so platforms can detect mismatches before initiating a flow. If they don't match, the agent fails mid-flow or requests scopes your server rejects.

Fix 3: Enforce PKCE

1. Authorization endpoint: accept code_challenge and code_challenge_method
2. Store: persist code_challenge with the authorization code
3. Token endpoint: require code_verifier
4. Validate: SHA256(code_verifier) must equal the stored code_challenge
5. Reject: return invalid_grant if code_verifier is missing or doesn't verify

Fix 4: Configure redirect URIs correctly

{
  "redirect_uris": [
    "https://yourstore.com/oauth/callback",
    "https://accounts.google.com/oauth/return",
    "https://chatgpt.com/oauth/callback"
  ]
}

For loopback URIs (native/desktop agent runtimes), match on scheme, host, and path only - ignore the port - per RFC 8252 Section 7.3.

Fix 5: Add issuer validation

Include the iss parameter in every authorization response, and ensure it matches your metadata issuer exactly. Agents validate iss to prevent Mix-Up Attacks.

How to test your fix

Identity Linking spans all four levels. Level 1 and 2 catch missing capability blocks and scope mismatches. Level 3 and 4 are where PKCE enforcement, redirect URI configuration, and token endpoint behavior are actually tested - a metadata document that looks correct on paper can still fail when an agent attempts the real flow. See the four levels of UCP validation.

Quick reference: Identity Linking requirements

Common related failures

• Missing signing_keys - agents need cryptographic verification before processing identity tokens
• Namespace/origin mismatch - an Identity Linking capability under a mismatched origin is treated as untrusted
• Payment handlers missing - once the user is identified, the agent still needs valid handlers to complete the purchase
• Incomplete Checkout capability - Identity Linking personalizes the experience, but Checkout must process the transaction

Last updated: May 2026. UCP spec version 1.2. Identity Linking (dev.ucp.common.identity_linking) enables user-authenticated commerce via OAuth 2.0 Authorization Code flow. Missing or broken Identity Linking does not prevent discovery - but it prevents the personalized experiences that convert repeat customers. UCPtools is an independent community tool - not affiliated with Google, Shopify, or the UCP consortium.