Reference note
UCP Identity Linking: connect accounts with OAuth
How UCP Identity Linking handles access levels, OAuth discovery, scopes, consent, tokens, and unauthenticated fallback.
Published . Part of the UCP implementation guide.
Identity Linking lets a UCP platform act through a user’s merchant account after explicit consent. The current version uses merchant-hosted OAuth 2.0 and distinguishes three levels of access.
Key takeaways
- Access can be public, agent-authenticated, or user-authenticated.
- OAuth handles identity; UCP assigns commercial meaning to scopes.
- Missing Identity Linking does not remove a capability from negotiation.
What are the three access levels?
The Identity Linking specification defines:
| Level | Authentication | Example |
|---|---|---|
| public | none | browse a public catalog |
| agent-authenticated | platform credentials | create a guest cart |
| user-authenticated | platform plus user token | saved addresses or order history |
Identity Linking bridges the last two levels. The platform obtains a token after user consent and presents it to protected operations.
How do UCP and OAuth split responsibilities?
UCP defines commerce scopes and the operations they gate. OAuth defines endpoints, flows, tokens, and the vocabulary accepted by the authorization server. The layers work together but remain distinct.
The merchant publishes OAuth metadata under RFC 8414. A protected resource can answer
with HTTP 401, WWW-Authenticate, and a resource_metadata link to
/.well-known/oauth-protected-resource. The platform then constructs its own
authorization request with its state, redirect_uri, and PKCE values.
continue_url must not transport a prebuilt OAuth request. It is reserved for hosted
steps outside OAuth, such as account creation or terms acceptance.
How are scopes declared?
UCP config.scopes declares hard gates. OAuth scopes_supported lists the complete
vocabulary accepted by the server. Scopes accepted by OAuth but absent from
config.scopes can unlock optional features without making authentication mandatory.
Runtime messages may signal identity_optional when linking would improve the result.
The agent can offer sign-in while preserving a valid guest path.
Capability negotiation remains independent
A capability is never excluded from the intersection merely because Identity Linking is missing. If both participants advertise Order, it remains negotiated. Scopes then decide which operations require a user token.
This separation preserves compatibility. A platform can use public Catalog or guest Checkout before it supports account linking. The merchant should not turn missing identity into general protocol incompatibility.
Handling an identity challenge
- The platform calls a gated operation without a token.
- The merchant returns 401 with protected-resource metadata.
- The platform discovers the authorization server.
- The user grants consent in the merchant interface.
- The platform exchanges the code with PKCE.
- It retries the operation with the granted scopes.
An insufficient token should produce a result distinct from no token. Logs can retain requested and granted scopes, but must never record the credential.
Security checklist
- host OAuth under the merchant domain;
- publish RFC 8414 and RFC 9728 metadata;
- use PKCE and validate
state; - request the minimum scopes;
- never place tokens in
continue_url; - preserve guest access where the capability allows it;
- revoke and refresh tokens under the merchant’s OAuth policy.
UCP discovery itself is documented in the
/.well-known/ucp manifest.
The complete merchant setup is covered in the UCP implementation guide.
Sources
- UCP, Identity Linking Capability
- RFC 8414, OAuth 2.0 Authorization Server Metadata
- RFC 9728, OAuth 2.0 Protected Resource Metadata
Back to the UCP implementation guide · All notes · Lire en français