Web Bot Auth
RFC 9421 · Ed25519 · IETF Web Bot Auth

How an AI agent proves itself to a merchant

An agent arrives at a merchant's API claiming to be a trusted shopping assistant. The merchant has never met it before. How does the merchant know the request is genuinely from that agent — and that nobody altered the order on the way?

This page is a live, working answer. Every signature below is produced by a real Ed25519 private key held by this server, and verified by merchant code that trusts nothing except the public key it downloads for itself.

✗ What doesn't work

User-Agent: ShoppingAssistant/1.0

A claim, typed by the client. Anyone can send this exact string. It proves nothing, and IP allow-lists break the moment the agent changes hosting.

✓ What does work

Signature-Input: sig1=("@method" "@authority" …)
Signature: sig1=:MEUCIQDf…:

Proof, computed with a private key the agent never shares. Forging it means breaking Ed25519. The merchant checks it with public information alone.

The idea

Two parties, one asymmetric keypair

Web Bot Auth is not a new cryptosystem. It is a convention that stitches three existing standards together so that any bot and any server can interoperate without pre-arranging anything between them.

AI AGENT 🔒 Ed25519 private key never leaves this side 🔓 public key, published at /.well-known/…directory MERCHANT holds no secret about this agent at all verifies with public key it fetches itself, over TLS signed request → Signature-Agent · Signature-Input · Signature ← GET the public key directory The asymmetry is the whole point The merchant can verify the agent's signature, but learns nothing that would let it impersonate the agent. No shared secret, no API key to leak, no registration step, no prior relationship required.

What the agent does

  1. Holds an Ed25519 private key.
  2. Publishes the matching public key as a JWKS at a well-known URL on its own domain.
  3. For every outbound request, builds a signature base from selected parts of that request.
  4. Signs those exact bytes and attaches three headers.

What the merchant does

  1. Reads Signature-Agent to learn where the keys live.
  2. Fetches that JWKS itself, over TLS.
  3. Finds the key whose thumbprint equals the claimed keyid.
  4. Rebuilds the signature base from the request it actually received and verifies.
The single most important line above: the merchant rebuilds the signature base itself. It never trusts a value the agent hands it. If even one covered byte differs from what was signed — a changed price, a different path, a swapped header — the reconstructed bytes differ, and Ed25519 verification fails.
Step zero

This agent's real identity

Everything below is live, read from this server's actual keypair. The private half sits on disk in the container and is never transmitted. The public half is what the whole internet is allowed to see.

The published public key (JWK)

Served at the well-known directory URL. kty, crv and x are the key itself; the rest is metadata.

GET /.well-known/http-message-signatures-directory
loading…

How keyid is derived — and why it can't be faked

The key id is not a label the agent chooses. It is a SHA-256 hash of the key's own canonical JSON (RFC 7638 thumbprint). The merchant recomputes it from the key it downloaded. So an agent cannot publish one key and claim a different identity — the id is a fingerprint of the key material.

1 · canonical JSON — required members only, sorted, no whitespace
loading…
2 · base64url( SHA-256( that string ) ) = keyid
loading…
Try it yourself — this is reproducible from the JWK above with nothing but a SHA-256 implementation:
echo -n '{"crv":"Ed25519","kty":"OKP","x":"…"}' | openssl dgst -sha256 -binary | basenc --base64url | tr -d '='
The handshake, step by step

One request, from signing to acceptance

The agent is placing a $37.00 coffee order. Follow the same request through both sides. Blue steps happen at the agent; purple steps happen at the merchant.

  1. The agent decides what to protect agent

    A signature only protects what it covers. The agent lists the parts of the request to bind — here the method, host, path, a hash of the body, and the Signature-Agent header. Anything left out can be altered in transit without breaking the signature.

    ("@method" "@authority" "@path" "content-digest" "signature-agent")

    The Web Bot Auth draft's baseline is just ("@authority" "signature-agent") — enough to prove who is calling. This demo covers more so the merchant can also prove what was ordered. Try the Baseline coverage only scenario below to see why that matters.

  2. The agent hashes the body agent

    To bind the order payload, the agent hashes it into a Content-Digest header (RFC 9530) and then signs that header. Signing a hash of the body is equivalent to signing the body, but keeps the signature base small.

    Content-Digest: sha-256=:base64 of SHA-256(request body):
  3. The agent builds the signature base agent

    This is the exact byte string that gets signed — one line per covered component, and a final @signature-params line carrying the metadata. This string is never transmitted; both sides construct it independently.

    live signature base from this server
    loading…
    Why created and expires are in there: without a time bound, one captured request would be a permanent credential. With it, a stolen request is useless after a few minutes.
    Why nonce: within that window, the nonce lets the merchant reject a second copy of the same request.
    Why tag="web-bot-auth": it pins the signature's purpose, so a signature made for something else cannot be repurposed as bot authentication.
  4. The agent signs and sends agent

    Ed25519 signs those bytes directly. The result goes into three headers — this is the entire on-the-wire footprint of Web Bot Auth.

    HeaderCarries
    Signature-AgentWhere to find the public keys. An https origin, quoted as a structured-field string.
    Signature-InputWhat was covered, and the parameters — created, expires, keyid, alg, nonce, tag.
    SignatureThe raw Ed25519 signature bytes, base64, wrapped in colons.
  5. The merchant finds and fetches the key merchant

    The merchant reads Signature-Agent, appends the well-known path, and fetches the JWKS over TLS. It then computes the thumbprint of each published key and looks for one matching the keyid in Signature-Input.

    Signature-Agent: "https://ai.abhinava.xyz"
              ↓
    GET https://ai.abhinava.xyz/.well-known/http-message-signatures-directory
              ↓
    for each key: SHA-256 thumbprint == keyid ?
    TLS is doing real work here. It is what ties the public key to the domain name in Signature-Agent. Fetching keys over plain HTTP would let anyone on the path substitute their own key — which is why the scheme must be https.
  6. The merchant rebuilds the base and verifies merchant

    Using the component list from Signature-Input, the merchant reconstructs the signature base from the request as it actually arrived — its own view of the method, host, path and headers. Then one Ed25519 verification against the downloaded public key decides the outcome.

    Before trusting it, the merchant also checks the clock window, the nonce, the tag, and that enough of the request was covered to satisfy its own policy. All of that runs live in the next section.

Live demo

Watch the merchant accept — and reject

Each scenario sends a real signed request to the merchant's verifier running on this server. Start with the valid one, then break a single thing at a time and watch exactly which check catches it.

Loading scenarios…

Live endpoints

The URLs this demo exposes

All of these are real and callable right now. The first one is the only endpoint Web Bot Auth actually requires you to publish.

EndpointWhat it is
/.well-known/http-message-signatures-directory The required one. The agent's public keys as a JWKS, served as application/http-message-signatures-directory+json. The response signs itself with tag="http-message-signatures-directory", so a merchant can confirm the key list came from the key holder.
/api/agent/identityThis agent's JWK, its keyid, and the exact canonical JSON the thumbprint was computed over.
/api/agent/sample-requestA freshly signed request you can replay with curl. Valid for 5 minutes.
POST /api/merchant/checkoutThe protected resource. Accepts only requests that pass full Web Bot Auth verification; returns the step-by-step trace either way.
/api/merchant/policyWhat this merchant requires — which components must be signed, clock skew, lifetime limits.
/api/demo/run?scenario=…Runs any scenario server-side and returns the whole trace as JSON.
Your turn

Prove it to yourself

1 · Send a signed request with curl

Generated fresh when this page loaded — the signature expires five minutes later, after which you'll get expired. Each one works exactly once; a second run gives replayed_nonce.

bash
loading…

2 · Sign a request yourself, in ~30 lines

Node 18+, no dependencies. Publish the printed JWK at your own domain's well-known path and the merchant will verify against your key.

agent.mjs
import { generateKeyPairSync, createHash, sign, randomBytes } from 'node:crypto';

const { publicKey, privateKey } = generateKeyPairSync('ed25519');
const { kty, crv, x } = publicKey.export({ format: 'jwk' });

// keyid = RFC 7638 thumbprint: SHA-256 over canonical {crv,kty,x}
const kid = createHash('sha256')
  .update(JSON.stringify({ crv, kty, x }))
  .digest('base64url');

const ORIGIN = 'https://your-agent.example';   // where YOUR jwks is published
const body   = JSON.stringify({ hello: 'merchant' });
const digest = `sha-256=:${createHash('sha256').update(body).digest('base64')}:`;

const created = Math.floor(Date.now() / 1000);
const params  = `;created=${created};expires=${created + 300};keyid="${kid}"`
              + `;alg="ed25519";nonce="${randomBytes(64).toString('base64')}"`
              + `;tag="web-bot-auth"`;
const covered = '("@method" "@authority" "@path" "content-digest" "signature-agent")';

// The signature base: one line per component, params last, joined with \n, no trailing newline.
const base = [
  '"@method": POST',
  '"@authority": ai.abhinava.xyz',
  '"@path": /api/merchant/checkout',
  `"content-digest": ${digest}`,
  `"signature-agent": "${ORIGIN}"`,
  `"@signature-params": ${covered}${params}`
].join('\n');

const sig = sign(null, Buffer.from(base), privateKey).toString('base64');

console.log(JSON.stringify({ keys: [{ kty, crv, x, kid, use: 'sig' }] }, null, 2));
console.log({
  'Signature-Agent': `"${ORIGIN}"`,
  'Content-Digest': digest,
  'Signature-Input': `sig1=${covered}${params}`,
  'Signature': `sig1=:${sig}:`
});
Watch out for these three. They account for almost every failed first attempt: the parameter string must be byte-identical in the signature base and in Signature-Input (build it once, reuse it); the signature base is joined with \n and has no trailing newline; and @authority is the host the request is addressed to — if you sign localhost:8080 but a proxy presents ai.abhinava.xyz, verification fails.
Reference

Every field, and what it's for

Signature parameters

ParameterRequiredPurpose
createdYesUnix seconds when signed. A merchant rejects values implausibly far in the future (clock skew allowance, typically ±5 min).
expiresYesUnix seconds after which the signature must be refused. Keep it short; the draft recommends no more than 24 hours, minutes are better.
keyidYesBase64url RFC 7638 thumbprint of the signing key. The merchant recomputes this from the published JWK rather than trusting it.
algRecommended"ed25519". Fast, small signatures, no parameter-choice footguns.
nonceRecommendedRandom, never reused. 64 bytes recommended. Enables replay rejection within the validity window.
tagYes"web-bot-auth". Binds the signature to this purpose so it can't be lifted from another context.

Covered components

ComponentBinds
@authorityThe host being addressed. Stops a signature captured by one site being replayed against another. Required by the draft.
signature-agentThe key directory URL. Must be signed if sent — otherwise an attacker could redirect the merchant to a directory of their own.
@methodStops a signed GET being replayed as a DELETE.
@pathStops a signature for one route being reused on another.
content-digestThe request body. Without it the signature says nothing about the payload — the order can be rewritten in flight.

What Web Bot Auth does and does not give you

It proves

  • The request was signed by the holder of a specific private key.
  • That key is published at a specific https domain.
  • Every covered part of the request is exactly as signed.
  • The signature was made recently, and (with a nonce cache) used only once.

It does not prove

  • That the operator of that domain is trustworthy — that is a policy decision you still own.
  • That the agent is acting for the user it claims. User delegation is a separate problem.
  • Anything about uncovered parts of the request.
  • That the key was not stolen. Rotate keys, and publish several so rotation is seamless.
Rotation, briefly. The directory is a set. Publish the new key alongside the old, start signing with the new one, and remove the old after any cached directory copies have expired. Merchants match on thumbprint, so nothing breaks mid-flight.

Specifications