UCP Identity Linking Mechanism Registry

A breaking redesign of UCP's identity linking system introduces a mechanism registry and capability-driven scopes, giving merchants granular control over how AI agents authenticate and what data they can access.

About the Author

Amit Handa

Amit Handa is a core contributor to the Universal Commerce Protocol, focusing on identity and authentication infrastructure. His work has shaped how agents establish trust with merchants in agentic commerce scenarios.

Why This Matters

The Universal Commerce Protocol has always needed a way for AI agents to prove they're acting on behalf of a specific user. The original identity linking approach was simple: agents would redirect users to OAuth flows, receive tokens, and use those tokens for subsequent requests. It worked, but it treated all identity links as equivalent.

The problem? A merchant authorizing an agent to check order status probably doesn't want that same authorization to place new orders. And different authentication methods (OAuth, passkeys, wallet signatures) have different trust levels that weren't being captured.

This PR introduces two major concepts that address these limitations:

Mechanism Registry: A formal registry of authentication mechanisms (oauth2, passkey, wallet, etc.) with standardized metadata about their properties and trust characteristics.
Capability-Driven Scopes: Identity links now carry explicit capability grants. An agent might have read:orders but not write:orders, and merchants can enforce this distinction.

What Changed Technically

The identity linking request/response structures have been redesigned:

{
  "identity_link": {
    "mechanism": "oauth2",
    "mechanism_version": "2.0",
    "capabilities": ["read:profile", "read:orders"],
    "binding": {
      "user_id": "usr_abc123",
      "issuer": "https://merchant.example.com"
    },
    "metadata": {
      "granted_at": "2026-03-19T04:42:20Z",
      "expires_at": "2026-04-19T04:42:20Z"
    }
  }
}

Key structural changes include:

Explicit mechanism declaration: The mechanism field replaces implicit detection, making the authentication method auditable.
Capability arrays: Fine-grained permissions replace binary "linked/not-linked" status.
Binding metadata: User identity and issuer information is now structured rather than opaque.
Temporal bounds: Grant and expiration timestamps enable time-limited authorizations.

The mechanism registry itself is defined in a new specification section that will grow as new authentication methods are standardized:

mechanisms:
  oauth2:
    trust_level: "delegated"
    revocable: true
    supports_scopes: true
  passkey:
    trust_level: "direct"
    revocable: false
    supports_scopes: false
  wallet:
    trust_level: "cryptographic"
    revocable: true
    supports_scopes: true

Migration Impact

This is a breaking change, marked with the conventional feat! prefix. Existing implementations using the old identity linking format will need to migrate:

Agents: Must update identity link request payloads to include mechanism and capability requirements.
Merchants: Must update token issuance to include structured capability grants.
Verification: Both sides must validate capability claims before proceeding with capability-guarded operations.

The UCP team recommends a 90-day migration window, with the old format deprecated but still functional until June 2026.

Next Steps

This PR sets the foundation for several upcoming capabilities:

Delegation chains: Agents delegating to sub-agents with capability attenuation.
Capability introspection: Endpoints for agents to query what they're authorized to do.
Audit logging: Structured capability grants enable better compliance tracking.