Ecosystem.
x401 is a thin protocol that depends on a thicker stack of existing standards and composes with several adjacent ones. The point is to be the boring HTTP glue that makes those standards usable from a route handler.
These are the load-bearing standards x401 references normatively. If you understand these, you understand x401.
OpenID for Verifiable Presentations 1.0
The wallet-facing presentation protocol. The agent constructs an OpenID4VP Authorization Request whose nonce and dcql_query come from the x401 payload.
Digital Credentials Query Language
Expresses what credentials, claims, and predicates a route requires. x401 carries a DCQL query verbatim in proof.dcql_query.
OAuth 2.0 Token Exchange
Powers the optional token leg. The agent exchanges a VP Artifact for a short-lived Verification Token using a fixed subject_token_type.
DIF Credential Trust Establishment
Document format for declaring approved issuers, schemas, and credential types. Referenced by URL from proof.issuers.trust_establishment_url.
OpenID for Verifiable Credential Issuance
Discovery mechanism for credential issuers when the trust list identifies them by Credential Issuer Identifier. Used for credential acquisition guidance.
HTTP Semantics
The status code and header registry x401 lives inside. 401 for proof, 402 for payment, 403 for failed policy.
Optional layers that compose cleanly with x401 without modifying its contract. Use them when your deployment needs them; skip them when it doesn't.
x402 — HTTP Payment Required
Sister protocol for payment. x401 and x402 compose without either absorbing the other.
Web Bot Auth + HTTP Message Signatures
Sign the protected-route request, retry, and token exchange to bind the HTTP caller to a public key directory or service identity.
OAuth Mutual TLS
Bind the OAuth token request and Verification Token to a certificate-controlled Agent Identifier.
DPoP
Application-layer proof-of-possession for OAuth tokens. Pairs naturally with the optional token leg under a deployment-specific profile.
SPIFFE / WIMSE
Workload identity sources for the Agent Identifier when the caller is a service rather than a user-facing application.
Verifiable Intent / GNAP / OAuth Actor Chain
Carry signed delegation mandates as a companion to the VP Artifact when the agent is acting on a holder's behalf.
Reference and community libraries.
The reference TypeScript implementation ships from the proof/x401-lib monorepo. Other languages and platforms welcome — see the contributing guide.
Any OpenID4VP-compliant wallet works at the protocol level.
Interop matrix coming with v0.2 — see tracking issue.
x401 governs proof. x402 governs payment.
x401 and x402 are deliberately orthogonal. x401 governs proof at the HTTP boundary; x402 governs payment at the same boundary. They share a design instinct (lean on HTTP semantics, refuse to absorb each other) and a coordination promise (a route can demand both, in either order, without either protocol trying to be the other).
See composing with payment for the recommended sequencing.
Help shape the protocol.
- Read the spec and open issues for design feedback.
- Join the discussion on open questions: machine payments, fully autonomous delegation, agent authentication.
- Build a verifier or agent library in your favorite language. We'll list it here.
- Run your wallet against the test vectors that ship with
@x401/coreand report what breaks.