Introducing x401: Bringing Proof of Identity to the Agent...

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

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", ...}

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

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

http

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

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

json

{
  "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"
}

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 */ } }

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):

json

{
  "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
}

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:

http

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

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

json

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

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:

json

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

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:

http

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>

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.

推荐订阅源

DEV Community