> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP security model and authentication methods

> UCP security model — API Keys, OAuth 2.0, mTLS, HTTP Message Signatures (RFC 9421), JWK signing keys, and Content-Digest (RFC 9530)

# Security and Authentication

## 6.1 Authentication Mechanisms Overview

UCP supports four authentication mechanisms, each suited to different security requirements:

| Mechanism                   | Standard      | Use Case                                            | Security Level |
| --------------------------- | ------------- | --------------------------------------------------- | -------------- |
| **API Keys**                | Custom        | Public catalog browsing, low-sensitivity operations | Basic          |
| **OAuth 2.0**               | RFC 6749/6750 | Identity linking, acting on behalf of a user        | Standard       |
| **mTLS**                    | RFC 8705      | High-security server-to-server communication        | High           |
| **HTTP Message Signatures** | RFC 9421      | Webhook signature verification, request integrity   | High           |

### API Keys

Suitable for scenarios that do not require user identity (e.g., browsing the public product catalog):

```http theme={null}
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:

```text theme={null}
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:

```json theme={null}
{
  "signing_keys": [
    {
      "kid": "key-2026-04",
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
```

**JWK Field Reference**:

| Field | Value     | Description                                                       |
| ----- | --------- | ----------------------------------------------------------------- |
| `kid` | string    | Key identifier, used to locate a specific key among multiple keys |
| `kty` | `EC`      | Key type: Elliptic Curve                                          |
| `crv` | `P-256`   | Curve: NIST P-256                                                 |
| `x`   | Base64URL | Elliptic curve public key X coordinate                            |
| `y`   | Base64URL | Elliptic curve public key Y coordinate                            |
| `use` | `sig`     | Usage: signing                                                    |
| `alg` | `ES256`   | Algorithm: 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)

```http theme={null}
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
```

**Step 2**: Define the Signature-Input

```http theme={null}
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

```text theme={null}
"@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)

```http theme={null}
Signature: sig1=:MEUCIQDXsM...base64_signature_value...=:
```

### Signature Verification (AI Agent Side)

```text theme={null}
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:

```http theme={null}
Content-Digest: sha-256=:base64_encoded_SHA-256_hash:
```

How to compute:

```text theme={null}
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

| Requirement                  | Description                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------- |
| **HTTPS required**           | All UCP communication must use HTTPS; the Profile endpoint must not redirect |
| **TLS 1.2+**                 | Minimum TLS 1.2; TLS 1.3 recommended                                         |
| **Certificate validation**   | AI agents must strictly validate merchant TLS certificates                   |
| **HSTS**                     | HTTP Strict Transport Security recommended                                   |
| **Certificate Transparency** | Certificates logged in CT logs recommended                                   |

## 6.6 Data Security and Privacy

UCP establishes clear security boundaries for data handling:

| Data Type                  | AI Agent Permissions                     | Prohibited Actions                |
| -------------------------- | ---------------------------------------- | --------------------------------- |
| Product catalog            | Cache and display to users               | Use for model training            |
| Buyer personal information | Pass to merchant to complete transaction | Store or share with third parties |
| Payment credentials        | Pass through Payment Handler             | Store, log, or forward            |
| Order data                 | Display to the corresponding consumer    | Aggregate analysis or data mining |
| Signing keys (private)     | Should never access private keys         | Any 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](/en/book-3/ch7-merchant-integration) — `/.well-known/ucp` Profile deployment and capability declaration