# How to Implement Web Bot Auth > A step-by-step guide for agents to sign HTTP requests cryptographically > using Ed25519 + HTTP Message Signatures. If you operate an AI agent, **Web Bot Auth** lets you prove your identity to any server using public-key cryptography — no API keys to distribute, no IP allowlists to maintain. A single key pair authenticates every request your agent makes, anywhere. This guide shows you exactly what to build. ## Why do this? - **Prove your agent is a real actor.** Servers can cryptographically verify your requests came from your infrastructure, not a spoofer. - **Get trusted without direct registration.** Pair this with a public allowlist (like [whitelist.dev](https://whitelist.dev)) and your agent is instantly recognized as legitimate by any service that checks it. - **No shared secrets.** Your private key never leaves your servers. Servers only need your public key (hosted at a well-known URL on your domain). - **Standards-based.** Built on published IETF drafts. Cloudflare and others are already rolling out verification at the edge. ## The protocol at a glance 1. You generate an Ed25519 key pair. 2. You host a JWKS directory at `/.well-known/http-message-signatures-directory` on your agent's operator domain, containing your public key. 3. For every outgoing request your agent makes, it computes a signature over a canonical set of HTTP components (using the private key) and attaches three headers: `Signature`, `Signature-Input`, `Signature-Agent`. 4. The server reading your agent's request fetches your public key from the URL in `Signature-Agent` and verifies the signature. That's the whole thing. Below are the exact details. --- ## Step 1 — Generate an Ed25519 key pair Ed25519 is the only algorithm currently required. The private key stays on your server; the public key goes in your JWKS directory. ```bash # Private key (keep this secret) openssl genpkey -algorithm ed25519 -out private-key.pem # Public key openssl pkey -in private-key.pem -pubout -out public-key.pem ``` If your OpenSSL is older than 1.1.1 (e.g. LibreSSL on macOS), use Python: ```python from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey from cryptography.hazmat.primitives import serialization pk = Ed25519PrivateKey.generate() priv_pem = pk.private_bytes( serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption(), ) pub_pem = pk.public_key().public_bytes( serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo, ) open("private-key.pem", "wb").write(priv_pem) open("public-key.pem", "wb").write(pub_pem) ``` ## Step 2 — Extract the raw public key (32 bytes) JWK format uses the raw 32-byte Ed25519 public key, base64url-encoded (no padding). Extract it from your public key file: ```python from cryptography.hazmat.primitives import serialization import base64 with open("public-key.pem", "rb") as f: pub = serialization.load_pem_public_key(f.read()) raw = pub.public_bytes( serialization.Encoding.Raw, serialization.PublicFormat.Raw, ) x = base64.urlsafe_b64encode(raw).rstrip(b"=").decode() print(x) # e.g. "LTzIiCXUxDVBfudGyQsESBPnKyDQ4c8Ecb9fTYrG3Mg" ``` ## Step 3 — Compute your JWK thumbprint This is a stable identifier for your key, per [RFC 8037]. It's the `keyid` you'll put in every request. ```python import hashlib, base64 canonical = f'{{"crv":"Ed25519","kty":"OKP","x":"{x}"}}' thumbprint = base64.urlsafe_b64encode( hashlib.sha256(canonical.encode()).digest() ).rstrip(b"=").decode() print(thumbprint) # e.g. "oLEigX9jWBZAQlSy3vAr5mT-McHCgEOPVzfC5Ol1oiY" ``` The canonical form **must** have keys sorted as `crv`, `kty`, `x` with no whitespace — this is the RFC 7638 canonicalization rule for Ed25519 keys. ## Step 4 — Host your JWKS directory Serve a JSON response at exactly this path on your agent's operator domain: ``` https://your-domain.com/.well-known/http-message-signatures-directory ``` The body is a JWK Set containing your public key(s): ```json { "keys": [{ "kty": "OKP", "crv": "Ed25519", "x": "LTzIiCXUxDVBfudGyQsESBPnKyDQ4c8Ecb9fTYrG3Mg" }] } ``` ### Sign the directory response itself To prove you control the domain, the directory **response** must be signed using the same key listed in it. This prevents anyone from mirroring your public key and claiming to be you. Required response headers: - `Content-Type: application/http-message-signatures-directory+json` - `Signature: sig1=::` - `Signature-Input: sig1=("@authority";req);alg="ed25519";keyid="";nonce="";tag="http-message-signatures-directory";created=;expires=` Note: `"@authority";req` uses the `req` parameter because this is a response signature that references the request's `Host` header. The signature base for the directory response is: ``` "@authority";req: your-domain.com "@signature-params": ("@authority";req);alg="ed25519";keyid="...";nonce="...";tag="http-message-signatures-directory";created=...;expires=... ``` Sign those exact bytes with your private key, base64-encode (standard base64, not base64url) the 64-byte output, and wrap in `:...:`. ## Step 5 — Sign outgoing requests For each request your agent makes, compute a signature over `@authority` and `signature-agent`. This binds the signature to both the server the agent is hitting and the URL of your key directory (preventing replay to a different server). ### The three headers you send ``` Signature-Agent: "https://your-domain.com" Signature-Input: sig1=("@authority" "signature-agent"); created=1735689600; keyid=""; alg="ed25519"; expires=1735693200; nonce=""; tag="web-bot-auth" Signature: sig1=:: ``` ### The signature base Exactly these bytes, newline-separated, with no trailing newline: ``` "@authority": "signature-agent": "" "@signature-params":