agentsclimarketplace
Sign in

Ucp identity linking

Skill fxp/agentic-commerce-skills/skills/02-identity/ucp-identity-linking

Establish the buyer's identity for a UCP transaction via the common identity_linking capability — guest checkout vs OAuth 2.0 account linking, requesting minimal scopes, and carrying a bearer token into the checkout session. Use when a checkout needs an account (saved addresses, loyalty, order history) or the merchant's UCP profile declares dev.ucp.common.identity_linking as required.From its SKILL.md

Install
npx -y skills add fxp/agentic-commerce-skills --skill ucp-identity-linking

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.9 KB, 912 tokens by cl100k_base, as published. Nobody here has run it

UCP Identity Linking

中文摘要：通过 UCP 公共能力 dev.ucp.common.identity_linking 确立买家身份——游客结算 vs OAuth 2.0 账号绑定,申请最小 scope,把 bearer token 带进 checkout session。需要账号信息或 商家 profile 声明该能力为必需时用。

When to use / 何时使用

  • Checkout needs saved addresses / payment methods / loyalty / order history.
  • The merchant profile lists dev.ucp.common.identity_linking (declared in ucp.capabilities).
  • The user says "use my account".

Otherwise prefer guest checkout — supply buyer fields inline on the checkout session. 否则用游客结算,直接在 session 上填 buyer。

UCP mapping / UCP 映射

dev.ucp.common.identity_linking lets a platform "obtain authorization to perform actions on a user's behalf via OAuth 2.0" (per the UCP spec). The resulting bearer token is sent on checkout requests as Authorization: Bearer {token}, alongside the required UCP-Agent header.

Two paths:

  • Guest — no token; populate buyer: { first_name, last_name, email, phone_number } on the session.
  • OAuth 2.0 linking — run the flow, then carry the token into checkout.

Inputs & Outputs / 输入与输出

Inputs: merchant /.well-known/ucp profile (OAuth config), mode (guest|oauth), minimal scopes.

Outputs

{ "identity": {
    "mode": "oauth",
    "access_token": "***",            // sent as: Authorization: Bearer ***
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "profile addresses orders.read"
} }

Guest: { "identity": { "mode": "guest" } } → fill buyer on the session instead.

Workflow / 工作流

  1. Decide mode. Default guest; escalate to OAuth only for a concrete need; tell the user why.
  2. Read OAuth config from the merchant UCP profile.
  3. Request minimal scopes (least privilege; don't ask write to read history).
  4. Run OAuth 2.0 (authorization code + PKCE). The user consents in their browser; the agent never touches raw credentials.
  5. Carry the token into checkout as Authorization: Bearer {token} (plus UCP-Agent, Idempotency-Key, Request-Id). Track expires_in; refresh as needed; never log tokens.
  6. Step-up if checkout later needs a scope you didn't request.

Edge cases & failure modes / 边界与失败

  • User declines linking → fall back to guest if allowed; else stop and explain.
  • Token expiry mid-flow → refresh; if refresh fails, re-prompt consent.
  • Scope creep → never silently broaden; request step-up with a reason.
  • Per-merchant identity → tokens are merchant-scoped; don't reuse across merchants.
  • PII → collect the minimum; never persist tokens/PII in plaintext or logs.

Worked example / 示例

User: "Use my Acme account so addresses autofill."

  1. Need = saved addresses → oauth, scopes profile addresses.
  2. Read Acme OAuth from profile → auth-code + PKCE; user consents in browser.
  3. Token (expires_in:3600) → send Authorization: Bearer … on PUT /checkout-sessions/{id}. No write scopes requested.

References / 参考

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Keep looking

Skills are one crate of 326,367. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.