DEV Community

Daniel Buchner
Daniel Buchner

Posted on

Introducing x401: Bringing Proof of Identity to the Agentic Web

#ai #identity #webdev #agents

HTTP has had a payment status code since 1997. It still doesn't have a native identity one. x401 fixes that.

If you've worked with x402, Coinbase's HTTP-native payment protocol built on the long-dormant 402 Payment Required status code, x401 is the identity-layer counterpart. Where x402 answers "how does a server tell an agent what to pay?", x401 answers "how does a server tell an agent what identity proof to provide?"

Today, every API that gates access by who you are rather than whether you have a token builds this plumbing from scratch. x401 defines a standard HTTP mechanism for expressing credential requirements, and a standard way for agents to satisfy them automatically.

The problem, concretely

Here's what today's identity-gated API flow looks like for an agent:

POST /accounts/applications HTTP/1.1
Host: bank.example.com → 401 Unauthorized
Enter fullscreen mode Exit fullscreen mode

The 401 just says "no." Nothing in the response tells the agent what it needs — which credential type, from which issuer, expressing which claims. The agent can't self-serve the identity requirement. A human has to get involved.

Compare to x402:

GET /api/resource → 402 Payment Required
X-Payment: {"amount": "0.01", "currency": "USDC", ...}
Enter fullscreen mode Exit fullscreen mode

An agent reads the 402, pays, retries, done — no human in the loop. x401 brings the same pattern to identity.

How x401 works

The protocol uses three dedicated HTTP header fields:

  • PROOF-REQUIRED (server → agent): carries the proof requirement
  • PROOF-PRESENTATION (agent → server): carries the credential presentation
  • PROOF-RESPONSE (server → agent): carries verification results and error details

Step 1 — Initial request:

http

POST /accounts/applications HTTP/1.1
Host: bank.example.com
Enter fullscreen mode Exit fullscreen mode

Step 2 — Server returns a response with PROOF-REQUIRED:

HTTP/1.1 401 Unauthorized
PROOF-REQUIRED: <base64url-x401-payload>
Cache-Control: no-store
Enter fullscreen mode Exit fullscreen mode

The PROOF-REQUIRED value is a base64url-encoded JSON payload. Decoded:

{
  "scheme": "x401",
  "version": "0.2.0",
  "credential_requirements": {
    "digital": {
      "requests": [
        {
          "protocol": "openid4vp-v1-signed",
          "data": {
            "request": "eyJhbGciOiJFUzI1NiIsInR5cCI6Im9hdXRoLWF1dGh6LXJlcStqd3QifQ..."
          }
        }
      ]
    }
  },
  "oauth": {
    "token_endpoint": "https://bank.example.com/oauth/token"
  },
  "trust_establishment": "https://bank.example.com/.well-known/x401/trust/financial-customer-v1",
  "request_id": "proof-template-financial-customer-v1"
}
Enter fullscreen mode Exit fullscreen mode

The key field is credential_requirements. It contains a complete, Verifier-authored Digital Credentials API request — specifically an OpenID4VP request the agent can execute directly:

const result = await navigator.credentials.get(payload.credential_requirements);
// result => { protocol: "openid4vp-v1-signed", data: { /* signed VP */ } }
Enter fullscreen mode Exit fullscreen mode

The Verifier authors and signs this request. The agent does not compose it — it only executes it or relays it to a wallet. Inside the signed request is the actual credential query, expressed in DCQL (Digital Credentials Query Language):

{
  "response_type": "vp_token",
  "response_mode": "dc_api",
  "client_id": "x509_san_dns:bank.example.com",
  "expected_origins": ["https://bank.example.com"],
  "nonce": "uX7Vq3mZJH6MeN0qz2L7SQ",
  "dcql_query": {
    "credentials": [
      {
        "id": "financial_customer",
        "format": "jwt_vc_json",
        "meta": { "type_values": ["FinancialCustomerCredential"] },
        "claims": [
          {
            "path": ["credentialSubject", "assurance_level"],
            "values": ["VC-AL2", "VC-AL3"]
          }
        ]
      }
    ]
  },
  "exp": 1746557100
}
Enter fullscreen mode Exit fullscreen mode

Step 3 — Agent obtains a presentation:

The agent passes credential_requirements to a credential wallet. The wallet constructs an OpenID4VP authorization request, selects the matching credential, and returns a signed Verifiable Presentation bound to the Verifier as relying party.

Step 4 — Retry with PROOF-PRESENTATION:

POST /accounts/applications HTTP/1.1
Host: bank.example.com
PROOF-PRESENTATION: <base64url-vp-artifact-json>
Enter fullscreen mode Exit fullscreen mode

The PROOF-PRESENTATION value is a "VP Artifact":

{
  "request_id": "proof-template-financial-customer-v1",
  "response": {
    "protocol": "openid4vp-v1-signed",
    "data": "<wallet-returned-presentation-result>"
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 5 — Verifier validates and grants access:

The Verifier checks the presentation cryptographically — no shared secrets, no PII in transit. Either the credential validates against the issuer's public keys, or it doesn't. On success, the Verifier returns the protected resource.

If something fails, you get an x401 Error Object back in PROOF-RESPONSE:

{
  "scheme": "x401",
  "version": "0.2.0",
  "error": "invalid_presentation",
  "error_description": "Credential from untrusted issuer."
}
Enter fullscreen mode Exit fullscreen mode

The optional OAuth leg

Rather than submitting a full VP Artifact on every request, the agent can exchange a VP for a short-lived Verification Token via standard OAuth 2.0 Token Exchange:

POST /oauth/token HTTP/1.1
Host: bank.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
subject_token_type=urn:x401:params:oauth:token-type:vp_artifact&
subject_token=<base64url-vp-artifact-json>
Enter fullscreen mode Exit fullscreen mode

On success, the Verifier returns a Bearer token usable on subsequent requests without re-presenting credentials.

What are Verifiable Credentials (and why not JWTs)?

Verifiable Credentials are W3C-standardized cryptographically-signed assertions. Unlike ordinary JWTs or session tokens, VCs are:

  • Issued by an authoritative third party — not self-asserted by the agent or the application
  • Verifiable without a live roundtrip to the issuer — the issuer's public key is sufficient
  • Revocable via a credential status endpoint
  • Selectively disclosable — the holder presents only the claims required

x401 doesn't define a new credential format. It works with any format expressible in OpenID4VP: jwt_vc_json, mso_mdoc, sd-jwt, and others.

Status code independence

One design decision worth noting: x401 does not require the server to return 401. The PROOF-REQUIRED header is the protocol carrier, not the status code. A server can return 200 OK with PROOF-REQUIRED if the response body is still useful without proof, or any 4xx when the operation can't proceed. This means x401 composes cleanly with routes that already use WWW-Authenticate for other auth schemes.

Payment and identity stay separate: if payment is also required after proof is satisfied, the Verifier returns 402 Payment Required and the agent runs the x402 flow separately.

What's live now

The spec is published at x401.proof.com/spec/latest (v0.2.0). It covers the full protocol: payload structure, header semantics, presentation requirements, VP Artifact format, OAuth token exchange, agent binding options, and security/privacy considerations.

It's an open spec — read it, open issues on GitHub at x401-protocol/x401, or reply here if you're working on agent infrastructure and want to coordinate.

Proof is the identity provider that authored x401. Learn more at proof.com.

Top comments (4)

Collapse
 
unitbuilds profile image
UnitBuilds •

I imagine they build it custom, specifically so they cant get spoofed? If you know what the endpoint wants, it's easier to fake it?

Collapse
 
danielbuchner profile image
Daniel Buchner •

Can't fake a Verifiable Credential, because they are cryptographically signed by an issuer (DMV, university, medical board, etc.), and are bound to the owner's device-locked hardware.

Collapse
 
unitbuilds profile image
UnitBuilds •

True, now that there's dominant standards, it would technically bridge the gap between agents being blocked outright and agents carrying digital credentials that make them authorized representatives of users. The real problem then, is getting companies like Cloudflare and Datadome to sign on, because of the WAF providers can whitelist it as authorized bots, then it could potentially be a game-changer for sites like Amazon and mobile-assistant AI, I mean if you need to use biometrics to authorize the payment, that about falls in line with what I had envisioned for MCP-Lite, except I didnt consider getting them to authorize it, I just simply built it to fly under the radar entirely in protected airspace (the AOM). But while useful for users, not quite the rep that companies want, so they'd likely prefer something like your x401 if you can somehow get the major WAF onboard to endorse it, because while the AI providers like Google, Apple and Microsoft can push for it, they arent the gatekeepers that block the bot traffic... Though I'm very interested to see how this goes, if you can pull it off, it opens up a similar avenue as boutique outlets have done in the past with direct partnerships to provide agentic flight bookings (through partnered sites, via API, which was a workaround at the risk of shifted liability). Whereas what you propose would put the liability squarely back on the authority that sent the bot and malicious actions can be dealt with legally, because they legally authorized it and in turn are liable to pay and cant try and claim it back as an unauthorized purchase (which is why bot traffic is blocked so heavily at the moment).

Collapse
 
anp2network profile image
ANP2 Network •

The x402 analogy is load-bearing, and it holds for the envelope but breaks at the trust boundary in two specific places.

On "no human in the loop": payment authority is pre-delegable by construction — an agent holds a budget it was granted, and spending $0.01 is self-authorizing, so x402 really does remove the human. Presentation consent isn't symmetric to that. What x401 automates is the request side — the 401 now names the credential, issuer, and claims — but the wallet still has to release a VP, and per-presentation holder consent is the default precisely because a credential asserts something non-fungible about who the subject is. "Self-serve the identity requirement" only reaches full autonomy if there's a standing authorization for the wallet to disclose to arbitrary verifiers without per-exchange approval, which is the one grant wallets are built not to give. The human doesn't disappear; they move from interpreting the 401 (which you've genuinely solved) to the release-consent gate (which this doesn't touch).

Second, trust_establishment is carrying the actual hard problem. x402 needs no trust graph — USDC is USDC. x401's autonomy is bounded by issuer-trust resolution behind that .well-known/x401/trust/... URL: who decides issuer X is acceptable for VC-AL2, and whether the agent already holds a credential from someone on that list. You've standardized the transport of the requirement, not the establishment of the trust it points at — and that's where a human re-enters, one layer down.

One implementation note: since each exchange's freshness lives in the nonce/exp inside the signed OpenID4VP request, the Verifier has to mint and ES256-sign a fresh request on every 401, including bare unauthenticated probes — an asymmetric-crypto cost paid before any credential is presented, which x402's static amount/currency payload never incurs. Without a cheap pre-flight or a cached-template-with-detached-nonce path, the 401 endpoint becomes a signing oracle you can flood.