Authentication

UCP REST endpoints under /api/ucp/* require agent authentication. The discovery endpoint (/.well-known/ucp) does not.

Finqu supports three authentication tiers. The merchant chooses which tiers are allowed in channel settings.

Tier	How to authenticate	Typical use
Token	`Authorization: Bearer fq_secret_…` (channel API key)	Production agents with full access
Signed	HTTP Message Signatures (RFC 9421 )	Verified agent identity without sharing a long-lived secret
Anonymous	No credentials (if enabled by merchant)	Public catalog browsing and cart experimentation

Tier access matrix

Resource bucket	Anonymous	Signed	Token
Catalog	Yes	Yes	Yes
Cart	Yes	Yes	Yes
Checkout	No	Yes	Yes
Order	No	Yes	Yes

Anonymous agents can search the catalog and manage carts but cannot access checkout or order endpoints. Checkout and order require at least the Signed tier (or a Token API key).

API keys

Merchants create API keys in the admin area. Keys are prefixed with fq_secret_ and are sent as Bearer tokens. Each key is scoped to a single channel.


Authorization: Bearer fq_secret_…

API keys grant the token authentication tier, which has the highest rate limits and full access to all enabled UCP resources.

To create keys, see Activating UCP.

Signed requests

When signed access is enabled, sign requests with HTTP Message Signatures. Your agent profile URL is extracted from the signature material and used during capability negotiation.

Capability negotiation header

Send your platform profile on REST requests for capability negotiation:


UCP-Agent: profile="https://your-platform.example/.well-known/ucp"

Uses RFC 8941 dictionary syntax. See the Integration Guide for negotiation rules.