UCP Authentication Mechanisms: Secure Communication Between Platforms and Businesses

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 (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) 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 (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.

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.

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.

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 (lines 95-98), this alternative requires no prior secret exchange.

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 (Authentication section, lines 73-81) – Defines the four supported mechanisms and the mandatory UCP-Agent binding rule (lines 94-101).

• 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 (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 (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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}