# UCP Authentication Mechanisms: Secure Communication Between Platforms and Businesses

> Discover UCP authentication mechanisms like API Keys, OAuth 2.0, mTLS, and RFC 9421 for secure platform-to-business communication. Enable interoperable messaging today.

- Repository: [Universal Commerce Protocol (UCP)/ucp](https://github.com/Universal-Commerce-Protocol/ucp)
- Tags: deep-dive
- Published: 2026-04-26

---

**The Universal Commerce Protocol (UCP) supports four first-class authentication mechanisms—API Keys, OAuth 2.0, mutual TLS (mTLS), and HTTP Message Signatures (RFC 9421)—that enable secure, interoperable messaging between storefront platforms and merchant businesses.**

The Universal Commerce Protocol (`Universal-Commerce-Protocol/ucp`) is an open specification designed to standardize commerce interactions while keeping onboarding frictionless. According to the source code, these **UCP authentication mechanisms** can be used anywhere a request or webhook is sent, allowing verifiers to confirm identity through multiple trust models. Each method integrates with the protocol’s discovery and binding requirements to ensure cryptographic integrity.

## The Four UCP Authentication Mechanisms

The specification defines four distinct approaches to authentication, as documented in [`docs/specification/overview.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/overview.md) (lines 73-81). Platforms and businesses may implement one or more depending on their security infrastructure:

- **API Keys** – Pre-shared secret strings exchanged out-of-band. The key is transmitted in a dedicated header (e.g., `x-api-key`) or as a query parameter. This suits simple server-to-server integrations where long-lived secrets are acceptable.

- **OAuth 2.0** – Standard bearer token flows (client-credentials, authorization-code, etc.). The token is sent in the `Authorization: Bearer <token>` header. This is ideal when delegated authority, token revocation, and scoped permissions are required.

- **mTLS** – Mutual TLS where the client presents an X.509 certificate. The TLS handshake authenticates the client automatically when the certificate’s public key is listed in the business’s `signing_keys`. This fits high-security environments already relying on certificate infrastructure.

- **HTTP Message Signatures** – Cryptographic signatures created from selected HTTP components (method, path, headers, body hash) as defined in **RFC 9421**. The signed request includes `Signature-Input` and `Signature` headers. This is the *preferred* mechanism for new participants because it enables permission-less onboarding without prior secret exchange.

## Discovery and Identity Binding

Authentication in UCP relies on a discovery mechanism that links credentials to verified identities.

### Profile Discovery via /.well-known/ucp

Every participant publishes a UCP profile at `/.well-known/ucp`. This JSON document contains a `signing_keys` array (defined in [`source/discovery/profile_schema.json`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/discovery/profile_schema.json)) that lists public keys available for signature verification. The profile also includes optional metadata indicating which API-key, OAuth, or mTLS credentials are accepted.

### The UCP-Agent Binding Rule

Regardless of which mechanism is used, implementations **MUST** verify that the authenticated identity aligns with the `UCP-Agent` header. As specified in [`docs/specification/overview.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/overview.md) (lines 94-101), every request must include the `UCP-Agent` header pointing to the caller’s profile URL. Verifiers must ensure that the authenticated principal (API-key identity, OAuth token subject, client certificate DN, or signature key ID) matches the profile identified by `UCP-Agent`.

## Implementation Examples by Mechanism

Below are minimal, runnable examples demonstrating each mechanism for a **checkout-session creation** request (`POST /checkout-sessions`).

### API Key Authentication

Send the pre-shared secret in a custom header. The business checks that the key matches an entry on file for the profile referenced by `UCP-Agent`.

```http
POST /checkout-sessions HTTP/1.1
Host: merchant.example.com
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Content-Type: application/json
X-API-Key: sk_live_01A2B3C4D5E6F7G8H9I0J
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "cart_id": "cart_123",
  "payment_handler_id": "com.example.pay"
}

```

### OAuth 2.0 Bearer Token

The platform obtains a bearer token from its OAuth 2.0 provider (e.g., via client-credentials flow) and includes it in the standard `Authorization` header.

```http
POST /checkout-sessions HTTP/1.1
Host: merchant.example.com
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6Ij...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "cart_id": "cart_123",
  "payment_handler_id": "com.example.pay"
}

```

### Mutual TLS (mTLS)

During the TLS handshake, the client presents a certificate. The merchant validates the certificate’s public key against the `signing_keys` entry in the platform’s profile.

```bash
curl --cert client-cert.pem --key client-key.pem \
  -H "UCP-Agent: profile=\"https://platform.example/.well-known/ucp\"" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"cart_id":"cart_123","payment_handler_id":"com.example.pay"}' \
  https://merchant.example.com/checkout-sessions

```

### HTTP Message Signatures

This method computes a signature over selected HTTP components (`@method`, `@authority`, `@path`, and specific headers). The `keyid` in the `Signature-Input` points to a JWK entry in the platform’s profile. As noted in [`docs/specification/signatures.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/signatures.md) (lines 95-98), this alternative requires no prior secret exchange.

```http
POST /checkout-sessions HTTP/1.1
Host: merchant.example.com
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Signature-Input: sig1=("@method" "@authority" "@path" "idempotency-key");keyid="platform-2026"
Signature: sig1=:MEUCIQDkZ...:

{
  "cart_id": "cart_123",
  "payment_handler_id": "com.example.pay"
}

```

## Key Specification Files

These source files define the complete authentication model:

- **[`docs/specification/overview.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/overview.md)** (Authentication section, lines 73-81) – Defines the four supported mechanisms and the mandatory `UCP-Agent` binding rule (lines 94-101).

- **[`docs/specification/signatures.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/signatures.md)** ("When Signatures Apply", lines 95-98) – Clarifies that API keys, OAuth, and mTLS are valid alternatives to Message Signatures.

- **[`source/discovery/profile_schema.json`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/discovery/profile_schema.json)** (`signing_keys` property) – Schema for the public key declarations used across all mechanisms to verify identity.

## Summary

- UCP supports **four authentication mechanisms**: API Keys, OAuth 2.0, mTLS, and HTTP Message Signatures (RFC 9421).
- **HTTP Message Signatures** are the preferred method for new participants, enabling permission-less onboarding via cryptographic proof.
- All mechanisms require **profile discovery** via `/.well-known/ucp` and must comply with the **`UCP-Agent` binding rule** to prevent identity spoofing.
- Public keys for verification are stored in the profile's **`signing_keys`** array, defined in the JSON schema.
- Authentication is **mechanism-agnostic** at the authorization layer; the business logic validates permissions after cryptographic identity is established.

## Frequently Asked Questions

### What is the preferred authentication mechanism for new UCP participants?

**HTTP Message Signatures** are the recommended approach for new implementations. According to the UCP specification, this method allows businesses to verify a platform's identity without any prior secret exchange, reducing onboarding friction while maintaining cryptographic security via RFC 9421.

### How does UCP ensure the authenticated identity matches the platform profile?

Every request must include the **`UCP-Agent`** header containing the caller's profile URL. As mandated in [`docs/specification/overview.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/docs/specification/overview.md) (lines 94-101), verifiers **MUST** confirm that the identity established through API keys, OAuth tokens, certificates, or signatures aligns with the public keys declared in the profile referenced by `UCP-Agent`.

### Can multiple authentication mechanisms be used simultaneously in UCP?

While a single request typically uses one mechanism, the protocol allows businesses to accept **multiple credential types** simultaneously by publishing supported methods in their `/.well-known/ucp` profile. However, each individual request must include the appropriate headers for one mechanism and satisfy the `UCP-Agent` binding rule.

### Where are public keys stored for signature verification?

Public keys are declared in the **`signing_keys`** array within the UCP profile (`/.well-known/ucp`), as defined in [`source/discovery/profile_schema.json`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/discovery/profile_schema.json). This array contains JWK (JSON Web Key) entries that platforms use to sign requests and that businesses use to verify HTTP Message Signatures, mTLS certificates, or other cryptographic proofs.