Skip to main content

​
Security and Authentication

​
6.1 Authentication Mechanisms Overview

UCP supports four authentication mechanisms, each suited to different security requirements:
MechanismStandardUse CaseSecurity Level
API KeysCustomPublic catalog browsing, low-sensitivity operationsBasic
OAuth 2.0RFC 6749/6750Identity linking, acting on behalf of a userStandard
mTLSRFC 8705High-security server-to-server communicationHigh
HTTP Message SignaturesRFC 9421Webhook signature verification, request integrityHigh

​
API Keys

Suitable for scenarios that do not require user identity (e.g., browsing the public product catalog): 
GET /ucp/catalog/products?query=shoes
Authorization: Bearer ucp_pk_live_xxxxxxxxxxxx
API Keys typically distinguish between test (ucp_pk_test_) and production (ucp_pk_live_) environments.

​
OAuth 2.0

See Chapter 3 for details. Used in scenarios that require acting on behalf of a consumer (checkout, order queries, etc.). UCP mandates the Authorization Code + PKCE flow.

​
mTLS (Mutual TLS)

Mutual TLS authentication requires both client and server to present certificates. Suitable for high-security communication between platforms: 
AI Agent <--mTLS--> Merchant API
  |                    |
  +- Client cert       +- Server cert
     (proves agent       (proves merchant
      identity)           identity)
mTLS follows RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and can be combined with OAuth 2.0.

​
HTTP Message Signatures (RFC 9421)

UCP Webhook notifications and critical API calls use HTTP Message Signatures to ensure integrity and authenticity. This is one of the most important mechanisms in the UCP security model.

​
6.2 JWK Signing Keys

Merchants publish their signing public keys in the /.well-known/ucp Profile using the JSON Web Key (JWK) format: 
{
  "signing_keys": [
    {
      "kid": "key-2026-04",
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
JWK Field Reference:
FieldValueDescription
kidstringKey identifier, used to locate a specific key among multiple keys
ktyECKey type: Elliptic Curve
crvP-256Curve: NIST P-256
xBase64URLElliptic curve public key X coordinate
yBase64URLElliptic curve public key Y coordinate
usesigUsage: signing
algES256Algorithm: ECDSA with SHA-256
Key Rotation: Merchants can publish multiple keys simultaneously in the signing_keys array (distinguished by different kid values), enabling smooth key rotation. Old keys are retained during the transition period while new signatures use the new key.

​
6.3 HTTP Message Signatures (RFC 9421)

​
Signature Creation (Merchant Side)

When a merchant sends a Webhook, it creates a signature following the RFC 9421 standard: Step 1: Compute the Content-Digest of the request body (RFC 9530) 
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Step 2: Define the Signature-Input 
Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04";alg="ecdsa-p256-sha256"
Signature component reference:
  • @method: HTTP method (e.g., POST)
  • @target-uri: Full request URI
  • content-digest: Request body digest
  • content-type: Content type
  • created: Signature creation timestamp (Unix time)
  • keyid: Corresponds to the JWK kid in the Profile
  • alg: Signature algorithm
Step 3: Construct the signature base string 
"@method": POST
"@target-uri": https://agent.example.com/webhooks/ucp
"content-digest": sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
"content-type": application/json
"@signature-params": ("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04";alg="ecdsa-p256-sha256"
Step 4: Sign the base string using the private key (ES256) 
Signature: sig1=:MEUCIQDXsM...base64_signature_value...=:

​
Signature Verification (AI Agent Side)

Verification Checklist:

1. Parse Signature-Input to extract keyid and covered components
2. Fetch the JWK public key by kid from merchant's /.well-known/ucp
3. Verify Content-Digest:
   - Compute SHA-256 hash of the request body
   - Compare with the value in the Content-Digest header
4. Reconstruct the signature base string following component order in Signature-Input
5. Verify the ES256 signature using the JWK public key
6. Check the created timestamp (reject signatures older than 5 minutes)
7. Verification passed -> process the Webhook
   Verification failed -> return 401, log security event

​
6.4 Content-Digest (RFC 9530)

The Content-Digest header provides integrity verification for the request body, preventing tampering during transmission: 
Content-Digest: sha-256=:base64_encoded_SHA-256_hash:
How to compute: 
1. Take the complete HTTP request body (raw bytes)
2. Compute SHA-256 hash
3. Base64-encode the result
4. Format: sha-256=:base64_value:
Content-Digest works in tandem with HTTP Message Signatures — the signature covers the Content-Digest header, and the Content-Digest covers the request body, forming a complete security chain.

​
6.5 Transport Security

RequirementDescription
HTTPS requiredAll UCP communication must use HTTPS; the Profile endpoint must not redirect
TLS 1.2+Minimum TLS 1.2; TLS 1.3 recommended
Certificate validationAI agents must strictly validate merchant TLS certificates
HSTSHTTP Strict Transport Security recommended
Certificate TransparencyCertificates logged in CT logs recommended

​
6.6 Data Security and Privacy

UCP establishes clear security boundaries for data handling:
Data TypeAI Agent PermissionsProhibited Actions
Product catalogCache and display to usersUse for model training
Buyer personal informationPass to merchant to complete transactionStore or share with third parties
Payment credentialsPass through Payment HandlerStore, log, or forward
Order dataDisplay to the corresponding consumerAggregate analysis or data mining
Signing keys (private)Should never access private keysAny form of retrieval

​
6.7 Security Best Practices

  1. Key rotation: Rotate JWK signing keys regularly. Publish both old and new keys in the Profile simultaneously to ensure a smooth transition.
  2. Rate limiting: Implement reasonable rate limits on all UCP endpoints.
  3. Audit logging: Maintain complete audit logs for all checkout and order operations.
  4. Signature time window: The created timestamp in Webhook signatures should be within 5 minutes.
  5. Token security: Access tokens must not appear in URL parameters or log files.
  6. CORS: UCP API endpoints should be configured with strict CORS policies.
  7. Input validation: All input parameters must be strictly validated for type and range.
Next chapter: Merchant Integration Guide — /.well-known/ucp Profile deployment and capability declaration