← Articles

UCP Identity Linking Gets a Complete Redesign

UCP Breaking Change March 16, 2026 · PR #265

About the Contributor

Amith Anda is a core contributor to UCP focusing on identity and security architecture. This PR represents a fundamental rethinking of how identity linking works in agentic commerce scenarios.

Why This Change Matters

Identity linking is the mechanism that allows AI agents to connect user identities across different systems — linking a user's merchant account to their payment provider, or their loyalty program to a specific retailer. Get this wrong, and you either have a security nightmare or a usability dead end.

The original UCP identity linking design worked, but it was showing cracks as enterprise adoption accelerated. The new design addresses three critical limitations:

Extensibility: The old design baked specific identity providers into the protocol. Adding new providers required spec changes.
Scope Control: There was no clean way to limit what data an identity link could access — it was all or nothing.
Discovery: Agents couldn't programmatically discover what identity linking mechanisms a merchant supported.

⚠️ Breaking Change: This PR carries the feat! prefix, indicating backward-incompatible changes. Existing identity linking implementations will need to migrate to the new mechanism registry pattern.

What Changed Technically

Mechanism Registry

The headline change is introducing a mechanism registry — a discoverable list of supported identity linking methods. Instead of hardcoding OAuth2, SAML, or proprietary methods, merchants now advertise their capabilities:

{
  "identityLinking": {
    "mechanisms": [
      {
        "type": "oauth2",
        "authorizationEndpoint": "https://merchant.example/oauth/authorize",
        "scopes": ["profile", "loyalty.read", "orders.read"]
      },
      {
        "type": "saml",
        "metadataUrl": "https://merchant.example/saml/metadata"
      }
    ]
  }
}

Capability-Driven Scopes

The second major change is capability-driven scoping. Rather than identity links granting blanket access, they now specify exactly what capabilities are unlocked:

profile — basic identity confirmation
loyalty.read — read loyalty points and tier status
loyalty.redeem — ability to redeem points
orders.read — view order history
orders.modify — change or cancel orders

This granularity is essential for enterprise adoption. A corporate travel agent can link to a hotel's loyalty program to read status without being authorized to redeem points — a common compliance requirement.

Migration Path

For existing implementations, the migration involves:

Exposing identity mechanisms in your capability document
Updating identity link requests to include scope arrays
Implementing scope validation on the merchant side

The PR includes a compatibility shim that maps old-style identity links to the new format with full scopes (essentially the "all or nothing" behavior), giving merchants time to implement proper scope handling.

Implications and Next Steps

This redesign opens several doors:

Decentralized Identity: The mechanism registry pattern makes it straightforward to add DID/Verifiable Credential support without protocol changes.
Zero-Knowledge Proofs: Capability-driven scopes lay groundwork for proving membership (e.g., "user is a Gold member") without revealing the underlying identity.
Audit Trails: Explicit scope grants make compliance reporting trivial — every identity link documents exactly what access was authorized.

The PR is still open for review. Given the breaking nature of the changes, expect a longer review cycle and potentially a dedicated migration window before this lands in a spec version.

For merchants and agent developers watching UCP, this is a good time to audit your current identity linking implementations and start planning for the mechanism registry pattern.