x401: native proof challenges for
APIs
AI Agents
Apps
Protected Routes
A universal HTTP-based challenge flow that enables resource gating based on fulfillment of credential proof requirements. x401 reuses OIDC4VP and optional OIDC4VCI hints, while leaving payment to 402 protocols.
Route-Scoped Gating
Challenge a single route or operation with a structured proof contract instead of app-specific glue.
OIDC Reuse
Reference standard OIDC4VP authorization requests without inventing a new presentation format.
Agent-Ready
Works for browsers, mobile apps, wallets, CLIs, and AI agents that need an HTTP-native retry loop.
How x401 Works
x401 mimics familiar HTTP challenge and retry flows using
401 Unauthorized as the protected-route proof boundary.
Key Features
x401 covers the protected-route contract that existing identity and issuance specs leave open.
HTTP-Native Challenge
Uses 401 Unauthorized and
WWW-Authenticate: x401 as the route-facing protocol
boundary.
OIDC4VP by Design
Reuses OIDC4VP objects directly instead of inventing a new presentation request format.
Advisory Issuance Hints
Points callers to possible credential sources with optional, non-authoritative OIDC4VCI metadata or offers.
By Value or by Reference
Verifiers can carry the proof request inline or hand off through
request_uri depending on transport needs.
Separate From Payment
Keeps proof semantics under x401 and leaves payment semantics to
402 Payment Required and a dedicated payment
protocol.
Human and Agent Flows
Supports wallets, applications, CLIs, and agent loops without forcing a browser-centric session model.
Technology Comparison
x401 is not a replacement for OIDC4VP or OIDC4VCI. It is the missing HTTP route contract that lets those capabilities show up where access decisions are actually made.
OAuth
Strong for delegated access and login, but not a general credential-proof challenge for a specific protected route.
OIDC VP/VCI
Excellent proof and issuance primitives, but they do not by themselves define the HTTP challenge contract at the route.
DIDComm
Useful peer messaging transport, but not the simplest fit for a plain HTTP API that needs a machine-readable 401 flow.
| Capability | API Keys | OAuth | OIDC VP/VCI | DIDComm | x401 |
|---|---|---|---|---|---|
| Protected-route HTTP 401 challenge | Partial | Partial | No | No | Yes |
| Wallet-grade verifiable presentation request | No | No | Yes | Partial | Yes |
| Issuance discovery hints attached to the challenge | No | No | Partial | No | Yes |
| Retry contract for browsers, apps, and agents | Partial | Partial | Partial | Partial | Yes |
| Proof kept distinct from HTTP 402 payment | No | No | No | No | Yes |
| Minimal custom application glue at the route edge | No | Partial | Partial | Partial | Yes |
Ready to implement x401?
Start with the draft spec, inspect the protocol model, and keep the demo isolated while the project site becomes the primary entry point.