---
updatedAt: 2026-10-20T09:11:56.000Z
agentTools:
  projectIndex: https://dev.proof.com/llms.txt
---

# x401

Protect your endpoints from agentic traffic with Digital Credentials.

AI agents now browse, buy, sign, and call APIs on behalf of people. Bot detection can only tell you a request is not human. [x401](https://x401.id/) tells you which person stands behind it, through [Digital Credentials](https://www.w3.org/TR/digital-credentials/).

x401 is an open protocol that extends the HTTP `401` flow. When a user agent requests a protected resource without identity, the endpoint responds `401` with an x401 `PROOF-REQUEST` header: a Digital Credentials Presentation request.

The user agent delegates the request to the user's **Wallet**. The user authenticates to their Wallet and approves the credential presentation. The user agent retries the protected resource with a `PROOF-RESPONSE` header: a Digital Credentials Presentation response.

After cryptographic verification of the presented [Verifiable Credential](https://www.w3.org/TR/vc-data-model-2.0/), the user gets access to the protected resource. x401 lets you seamlessly harness the power of Proof's Digital Credentials through [Verify Identity](https://dev.proof.com/docs/verify-identity) and [Sign Transactions](https://dev.proof.com/docs/sign-transactions).

x401 is built on top of Digital Credentials and is wallet-agnostic; see the [specification](https://x401.proof.com/spec/latest/). Proof's **Cloud Wallet** supports x401 through [OpenID for Verifiable Presentations](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) (OID4VP).

<Callout theme="okay">
  Proof Cloud Wallet is also available as a [Web Component](https://github.com/proof/proof-vc-web) for your website!
</Callout>

<svg viewBox="0 0 820 564" width="100%" role="img" aria-label="x401 sequence: user agent, your endpoint, Proof Cloud Wallet"><defs ><marker id="x401-arrow-indigo" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="#6366F1" /></marker><marker id="x401-arrow-green" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" fill="#10B981" /></marker></defs><line x1="125" y1="60" x2="125" y2="558" stroke="currentColor" strokeOpacity="0.18" strokeWidth="1.5" strokeDasharray="4 6" strokeLinecap="round" /><rect x="33" y="14" width="184" height="44" rx="22" fill="#94A3B8" fillOpacity="0.12" stroke="#94A3B8" strokeOpacity="0.55" strokeWidth="1.5" /><text x="125" y="41" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="16" fontWeight="600" fill="#94A3B8">User agent</text><line x1="410" y1="60" x2="410" y2="558" stroke="currentColor" strokeOpacity="0.18" strokeWidth="1.5" strokeDasharray="4 6" strokeLinecap="round" /><rect x="318" y="14" width="184" height="44" rx="22" fill="#6366F1" fillOpacity="0.12" stroke="#6366F1" strokeOpacity="0.55" strokeWidth="1.5" /><text x="410" y="41" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="16" fontWeight="600" fill="#6366F1">Your endpoint</text><line x1="680" y1="60" x2="680" y2="558" stroke="currentColor" strokeOpacity="0.18" strokeWidth="1.5" strokeDasharray="4 6" strokeLinecap="round" /><rect x="588" y="14" width="184" height="44" rx="22" fill="#10B981" fillOpacity="0.12" stroke="#10B981" strokeOpacity="0.55" strokeWidth="1.5" /><text x="680" y="41" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="16" fontWeight="600" fill="#10B981">Proof Cloud Wallet</text><line x1="141" y1="108" x2="406" y2="108" stroke="#6366F1" strokeWidth="2" markerEnd="url(#x401-arrow-indigo)" strokeLinecap="round" /><text x="267.5" y="98" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">GET /protected</text><circle cx="125" cy="108" r="11" fill="#6366F1" /><text x="125" y="112" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">1</text><line x1="394" y1="164" x2="129" y2="164" stroke="#6366F1" strokeWidth="2" markerEnd="url(#x401-arrow-indigo)" strokeLinecap="round" strokeDasharray="6 5" /><text x="267.5" y="154" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">401 + PROOF-REQUEST</text><circle cx="410" cy="164" r="11" fill="#6366F1" /><text x="410" y="168" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">2</text><line x1="141" y1="220" x2="676" y2="220" stroke="#10B981" strokeWidth="2" markerEnd="url(#x401-arrow-green)" strokeLinecap="round" /><text x="402.5" y="210" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">Presentation request</text><circle cx="125" cy="220" r="11" fill="#10B981" /><text x="125" y="224" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">3</text><rect x="522" y="260" width="292" height="32" rx="10" fill="#10B981" fillOpacity="0.10" stroke="#10B981" strokeOpacity="0.45" strokeWidth="1" /><text x="674.0" y="280.5" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">User authenticates and approves</text><circle cx="522" cy="276" r="11" fill="#10B981" /><text x="522" y="280" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">4</text><line x1="664" y1="332" x2="129" y2="332" stroke="#10B981" strokeWidth="2" markerEnd="url(#x401-arrow-green)" strokeLinecap="round" strokeDasharray="6 5" /><text x="402.5" y="322" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">vp\_token</text><circle cx="680" cy="332" r="11" fill="#10B981" /><text x="680" y="336" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">5</text><line x1="141" y1="388" x2="406" y2="388" stroke="#6366F1" strokeWidth="2" markerEnd="url(#x401-arrow-indigo)" strokeLinecap="round" /><text x="267.5" y="378" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">GET /protected + PROOF-RESPONSE</text><circle cx="125" cy="388" r="11" fill="#6366F1" /><text x="125" y="392" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">6</text><rect x="328.0" y="428" width="164" height="32" rx="10" fill="#6366F1" fillOpacity="0.10" stroke="#6366F1" strokeOpacity="0.45" strokeWidth="1" /><text x="416.0" y="448.5" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">Verify vp\_token</text><circle cx="328.0" cy="444" r="11" fill="#6366F1" /><text x="328.0" y="448" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">7</text><line x1="394" y1="500" x2="129" y2="500" stroke="#6366F1" strokeWidth="2" markerEnd="url(#x401-arrow-indigo)" strokeLinecap="round" strokeDasharray="6 5" /><text x="267.5" y="490" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="14" fill="currentColor">200 + protected resource</text><circle cx="410" cy="500" r="11" fill="#6366F1" /><text x="410" y="504" textAnchor="middle" fontFamily="Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif" fontSize="11" fontWeight="700" fill="#FFFFFF">8</text></svg>

## Getting started

Implement x401 with Proof's Cloud Wallet and start verifying identities immediately.

Ask your agent to protect your endpoints behind x401 using Proof's Cloud Wallet:

> Protect my API endpoints behind the x401 protocol, using Proof's Cloud Wallet, following the instructions at <https://api.proof.com/.well-known/agent-skills/setup-x401-verifier/SKILL.md>

Or follow the step-by-step guide.

## 1. Install dependencies

```bash Terminal
npm install express @proof.com/x401-node @proof.com/proof-vc-server
```

## 2. Generate a key pair

The key pair signs your [OID4VP](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) requests and your enrollment. It uses `P-256`.

```bash Terminal
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
```

## 3. Host an OAuth Client ID Metadata Document

Create an [OAuth Client ID Metadata Document](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html) (CIMD) and host it at an endpoint you own, publicly accessible over HTTPS. The `CLIENT_ID` is the exact URL of the document.

```javascript client-metadata.mjs
import express from "express";
import { readFileSync } from "node:fs";
import { createPrivateKey, createPublicKey } from "node:crypto";
import { agentsTrustListUrl, createClientIdMetadataDocument } from "@proof.com/proof-vc-server";

// Your domain host
const domain = "";
// The exact URL at which the Client ID Metadata Document is hosted.
const CLIENT_ID = `https://${domain}/.well-known/proof-client.json`;
const privateKey = createPrivateKey(readFileSync("private-key.pem"));
const publicJwk = createPublicKey(privateKey).export({ format: "jwk" });
// "sandbox" for testing, "production" for production.
const environment = "sandbox";

const app = express();

const document = await createClientIdMetadataDocument({
  environment,
  clientId: CLIENT_ID,
  // Your business name, shown to users when they approve
  // a credential presentation for your endpoints.
  clientName: "Acme Corporation",
  // The agents allowed to use x401 with Proof's Cloud Wallet at your endpoints:
  // your own agents (by URL) or Proof's trusted list with `agentsTrustListUrl`.
  redirectUris: [agentsTrustListUrl(environment)],
  jwks: [publicJwk],
});

app.get("/.well-known/proof-client.json", (req, res) => {
  res.json(document);
});

export { app, CLIENT_ID };
```

> 📘 Agents trust list
>
> `agentsTrustListUrl` defines which trusted agents use x401 and Proof's Cloud Wallet at your endpoints. Proof publishes its list at <https://api.proof.com/.well-known/agents-trust-list>. See the OID4VP over the Digital Credentials API [`expected_origins`](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-openid4vp-over-the-digital-) parameter for details.
>
> Proof's Cloud Wallet accepts an OID4VP request only when its `expected_origins` are listed in the CIMD's `redirectUris`.

## 4. Register your OAuth Client ID Metadata Document

Enroll on Proof as an x401 **Verifier** by registering your CIMD, then follow the instructions received by email to complete your enrollment.

```bash Terminal
npx @proof.com/proof-vc-server enroll https://example.com/.well-known/proof-client.json --email admin@example.com --key private-key.pem --environment sandbox
```

> 📘 Email address
>
> The email address must be on the registrable domain of your CIMD's host. `www.` is treated as the apex domain. For example, `admin@example.com` works for `https://example.com`, `https://www.example.com` and `https://app.example.com`.

## 5. Protect your endpoint

Create an `x401Middleware` that inspects the request's `PROOF-RESPONSE` header and cryptographically verifies the presented `vp_token` containing the Verifiable Credential.

```javascript x401-middleware.mjs
import { app, CLIENT_ID } from "./client-metadata.mjs";
import { readFileSync } from "node:fs";
import { createPrivateKey, randomUUID } from "node:crypto";
import { verifier as x401, HEADER, DC_API_PROTOCOL } from "@proof.com/x401-node";
import { agentsTrustListUrl, createClient, createVerifier } from "@proof.com/proof-vc-server";

const privateKey = createPrivateKey(readFileSync("private-key.pem"));
const environment = "sandbox";

const proofClient = createClient({
  environment,
  clientId: CLIENT_ID,
  // Signs your OID4VP requests.
  useSecuredAuthorizationRequest: true,
  privateKeyFactory: () => privateKey,
});
const proofVerifier = createVerifier({
  environment,
  clientId: CLIENT_ID,
  // Fetches the detached signatures of the vp_token from Proof. See step 6.
  privateKeyFactory: () => privateKey,
});
// Nonces of pending OID4VP requests. Use a shared store in production.
const nonces = new Set();

async function x401Middleware(req, res, next) {
  const response = req.get(HEADER.PROOF_RESPONSE);

  if (response === undefined) {
    // Prevents replay attacks: each nonce is accepted once.
    const nonce = randomUUID();
    nonces.add(nonce);
    // A signed OID4VP request over the Digital Credentials API.
    const request = await proofClient.signedDcApiRequest({
      // See https://dev.proof.com/docs/verify-a-credential#scopes-and-claims
      scope: "urn:proof:params:scope:verifiable-credentials:basic",
      nonce,
      // A subset of the redirectUris of your CIMD.
      expectedOrigins: [agentsTrustListUrl(environment)],
    });
    // The PROOF-REQUEST header, following the x401 protocol.
    const payload = x401.buildPayload({
      credentialRequirements: {
        digital: {
          requests: [{ protocol: DC_API_PROTOCOL.SIGNED, data: { request } }],
        },
      },
    });
    return res
      .status(401)
      .set(HEADER.PROOF_REQUEST, x401.encodePayload(payload))
      .send("x401 PROOF-RESPONSE required");
  }

  try {
    const artifact = x401.decodeResultArtifact(response);
    // The credential result is inline, or behind a URL your endpoint fetches.
    let credentialResult = null;
    if (artifact.credential_result_uri === undefined) {
      credentialResult = artifact.credential_result;
    } else {
      const response = await fetch(artifact.credential_result_uri);
      credentialResult = await response.json();
    }
    // Verifies the vp_token, issued by Proof's Certificate Authority.
    // See https://dev.proof.com/docs/proof-certificate-authority
    const presentation = await proofVerifier.verifyVPToken({
      encodedVPToken: credentialResult.data.vp_token,
      aud: CLIENT_ID,
    });
    req.credential = presentation.proof_id_default[0];
    if (!nonces.delete(req.credential.getNonce())) {
      return res.status(401).send("x401 PROOF-RESPONSE replayed");
    }
  } catch {
    return res.status(401).send("x401 PROOF-RESPONSE invalid");
  }
  next();
}

app.get("/protected", x401Middleware, (req, res) => {
  // Reachable by user agents presenting a valid Verifiable Credential.
  res.json({ message: "Access granted", claims: req.credential.toJSON() });
});

app.listen(3000);
```

> ⚠️ Prevent replay attacks
>
> Verifiers MUST compare `req.credential.getNonce()` with the nonce of their OID4VP request and accept each nonce only once.

> 📘 Claims and scopes
>
> Learn about the [claims](https://dev.proof.com/docs/verifiable-credential-types) supported by Proof's Verifiable Credentials and how to request them with [scopes](https://dev.proof.com/docs/verify-a-credential#scopes-and-claims).

## 6. (Optional) Use with x402

You can decide to pay for x401 transactions with x402. When paying with x402, Proof delivers x401 presentations with detached signatures: the `vp_token` is readable, but not verifiable until your endpoint fetches its signatures from Proof, authenticated with the key pair of step 2:

[`POST https://api.proof.com/verifiable-credentials/v1/x401-signatures`](https://dev.proof.com/reference/getx401signatures)

`verifyVPToken` fetches the signatures for you. The endpoint responds `402 Payment Required` when the presentation is not paid yet, and accepts [x402](https://www.x402.org) payments in USDC on Base (version 2, scheme `exact`). Pass an x402-capable `fetch` to the verifier to pay automatically:

```bash Terminal
npm install @x402/fetch @x402/evm viem
```

```javascript x401-middleware.mjs
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

// Your wallet, funded with USDC on Base (Base Sepolia in sandbox).
const wallet = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);

// Replaces proofVerifier from step 5.
const proofVerifier = createVerifier({
  environment,
  clientId: CLIENT_ID,
  privateKeyFactory: () => privateKey,
  // Pays 402 Payment Required responses with x402.
  fetch: wrapFetchWithPaymentFromConfig(fetch, {
    schemes: [{ network: "eip155:*", client: new ExactEvmScheme(wallet) }],
  }),
});
```

> 📘 Paying without x402
>
> Verifiers who do not use x402 can add a credit card or link their bank account to their Proof account. Presentations are delivered with their signatures and can be verified immediately. They are charged to the default payment method.

Learn how the signatures are fetched and paid in [Use with x402](https://dev.proof.com/docs/x401-signatures).

## 7. Test your endpoint

The endpoint returns HTTP `401` with a `proof-request` header. Inspect the Digital Credentials Presentation request, then the OID4VP request it carries:

```bash Presentation request
curl -so /dev/null -w '%header{proof-request}' https://example.com/protected \
  | jq -R 'gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'
```
```bash OID4VP request
curl -so /dev/null -w '%header{proof-request}' https://example.com/protected \
  | jq -R 'gsub("-";"+") | gsub("_";"/") | @base64d | fromjson
    | .credential_requirements.digital.requests[0].data.request
    | split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'
```

Then ask your agent to fetch the protected resource with Proof's Cloud Wallet:

> Please install the Proof MCP <https://mcp.proof.com/mcp>, follow its instructions, then fetch `<your protected URL>`

With a valid `PROOF-RESPONSE`, the endpoint returns `200` and the verified claims.

## Go to production

Set `environment` to `"production"` and enroll:

```bash Terminal
npx @proof.com/proof-vc-server enroll https://example.com/.well-known/proof-client.json --email admin@example.com --key private-key.pem
```

## Cloudflare Workers

x401 also ships as a Cloudflare Workers library, [`@proof.com/x401-workers`](https://github.com/proof/x401-workers). Install it and plug x401 on top of your routes, with Hono or a plain Worker.

```bash Terminal
npm install @proof.com/x401-workers
```

```typescript worker.ts
import { Hono } from "hono";
import { agentsTrustListUrl, d1NonceStore } from "@proof.com/x401-workers";
import { x401, type X401Variables } from "@proof.com/x401-workers/hono";

type Env = { DB: D1Database; SIGNING_JWK: string };

const app = new Hono<{ Bindings: Env; Variables: X401Variables }>();

// Every route under /protected now requires a Verifiable Credential.
app.use(
  "/protected/*",
  x401<{ Bindings: Env }>((c) => ({
    clientId: CLIENT_ID,
    privateKeyFactory: () => JSON.parse(c.env.SIGNING_JWK),
    nonceStore: d1NonceStore(c.env.DB),
    scope: "urn:proof:params:scope:verifiable-credentials:basic",
    expectedOrigins: [agentsTrustListUrl(environment)],
  })),
);

app.get("/protected", (c) => c.json(c.var.x401.proof_id_default[0]?.toJSON()));

export default app;
```

Find out more in [Use on Cloudflare Workers](https://dev.proof.com/docs/x401-cloudflare).

## Resources

* [`@proof.com/proof-vc-server`](https://github.com/proof/proof-vc-common/tree/main/packages/server)
* [`@proof.com/x401-node`](https://github.com/proof/x401-node)
* [`@proof.com/x401-workers`](https://github.com/proof/x401-workers)
* [Digital Credentials overview](https://dev.proof.com/docs/digital-credentials-overview)
* [Integration guide](https://dev.proof.com/docs/integration)
* [OAuth Client ID Metadata Document (draft 02)](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-02.html)
* [OpenID for Verifiable Presentations (OID4VP) 1.0](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html)
* [Use on Cloudflare Workers](https://dev.proof.com/docs/x401-cloudflare)
* [Use with x402](https://dev.proof.com/docs/x401-signatures)
* [x401 specification](https://x401.proof.com/spec/latest/)
* [x402 protocol](https://www.x402.org)

![]()