com.agentscore.identity v1

1. Introduction

A vendor capability that declares a UCP merchant runs the AgentScore identity gate before transactional endpoints settle.

UCP itself defines product discovery, capability negotiation, checkout, and post-purchase handoff, but does not define identity verification. The com.agentscore.identitycapability fills that gap. When advertised on a UCP profile, it tells the agent: this merchant runs KYC, sanctions screening, age verification, and jurisdiction checks via the AgentScore API. Agents that don't recognize the capability still see all the standard UCP capabilities (catalog, cart, checkout) and can transact through whichever capabilities the merchant supports without identity gating; agents that do recognize it can pre-flight the identity check and recover gracefully when verification is needed.

2. Capability declaration

The capability is keyed under com.agentscore.identity (reverse-DNS, namespace authority agentscore.com) inside the UCP profile's capabilities map. It uses UCP's multi-parent extends to inherit from both the cart and checkout capability roots, so an agent that reads either parent picks up the AgentScore policy contract automatically.

Example binding inside ucp.capabilities:

"com.agentscore.identity": [
  {
    "version": "2026-04-08",
    "spec": "https://www.agentscore.com/specification/identity",
    "schema": "https://www.agentscore.com/schemas/ucp/com-agentscore-identity-v1.json",
    "extends": ["dev.ucp.shopping.checkout", "dev.ucp.shopping.cart"],
    "config": {
      "require_kyc": true,
      "require_sanctions_clear": true,
      "min_age": 21,
      "allowed_jurisdictions": ["US"]
    }
  }
]

3. Configuration

The schema for the binding's config object lives at /schemas/ucp/com-agentscore-identity-v1.json. All fields are optional; the merchant declares which AgentScore checks the gate enforces.

Fields:

• require_kyc (boolean): gate denies if the operator/account behind the agent is not Stripe-Identity-verified.
• require_sanctions_clear (boolean): gate denies if the operator/account is flagged by OpenSanctions screening (OFAC, UN, EU, UK, etc.).
• min_age (integer): gate denies if the verified age (from KYC) is below this threshold. Common values: 18, 21.
• allowed_jurisdictions (array of ISO-3166-1 alpha-2): country codes the gate accepts. Empty/absent allows any. Mutually exclusive with blocked_jurisdictions.
• blocked_jurisdictions (array of ISO-3166-1 alpha-2): country codes the gate denies. Empty/absent denies none. Mutually exclusive with allowed_jurisdictions.

4. Agent flow

End-to-end flow when an agent encounters a merchant that advertises the capability:

1. Discover. Agent fetches /.well-known/ucp, sees com.agentscore.identity in capabilities, and notes the config requirements (KYC, age, jurisdiction).
2. Pre-flight (optional). Agent that already has an operator credential or wallet identity can call AgentScore POST /v1/assess ahead of time to confirm the identity will pass the merchant's policy. Returns allow or a denial reason.
3. Transact. Agent attaches identity (X-Operator-Token or X-Wallet-Address) on the request to the merchant's transactional endpoint.
4. Gate. Merchant's SDK middleware (agentscoreGate in Node, AgentScoreGate in Python) calls AgentScore /v1/assess with the merchant's policy. On allow, the request flows through; on deny, the gate returns a 4xx with structured recovery instructions.
5. Settle. If allowed and the request was a 402 retry, the merchant verifies the payment credential (Stripe SPT / Tempo / Solana / x402) and returns 200 + the resource.

5. Recovery contract

When the gate denies, the response body carries a structured agent_instructions block describing the recovery action. Agents act from the response; no inference required.

Denial codes and their recovery actions:

• missing_identity → probe_identity_then_session (try wallet on signing rails → stored opc_... → session flow)
• identity_verification_required → deliver_verify_url_and_poll (auto-minted session in body, agent opens verify_url + polls poll_url)
• wallet_signer_mismatch → resign_or_switch_to_operator_token (body carries claimed_operator, actual_signer_operator, expected_signer, linked_wallets)
• token_expired → deliver_verify_url_and_poll (auto-minted session, identical UX to bootstrap)
• wallet_not_trusted → contact_support (UNFIXABLE: sanctions_flagged / age_insufficient / jurisdiction_restricted; KYC re-verification won't change the outcome)

6. Security considerations

• No PII at the merchant. The merchant only sees the gate's allow/deny verdict + derived facts (verified, age_bracket, jurisdiction, sanctions_status). Raw PII (name, address, government ID images, date of birth) is never shared.
• PII at AgentScore. Identity verification is handled by Stripe Identity (KYC + age) and OpenSanctions (sanctions). Both process PII transiently; AgentScore stores only the derived results.
• Credential rotation. Operator credentials default to a 24h TTL (configurable 1-365 days). Wallet-bound identities have no TTL but can be revoked at the operator level.
• Cross-merchant portability. Once an operator is verified, the same Passport works on every AgentScore-gated merchant in the agentic economy without re-verifying per site.

See also

• Identity flow: docs.agentscore.com/passport
• Compliance gating guide: docs.agentscore.com/compliance-gating
• Merchant SDKs: @agent-score/commerce (Node) and agentscore-commerce (Python)
• API reference: POST /v1/assess · POST /v1/sessions · POST /v1/credentials