Agent identities

Sign requests

Make every HTTP request your agent sends carry its Passport: three headers under Web Bot Auth (HTTP Message Signatures, RFC 9421), signed with the agent’s Ed25519 key. Use the SDK, or sign with any Web Bot Auth library. This page also shows how to set an agent up from code: registered, its key made where it runs and published.

What a signed request carries

HTTP
POST /api/orders HTTP/1.1
Host: shop.example
Signature-Agent: "https://acme.agents.pidgeon.ai"
Signature-Input: sig1=("@authority" "signature-agent" "@method" "@path" "@query");created=1794680108;keyid="KUqU0uc-fPnz0RGiU5gdnMXYaa6FUqqDKcy-oa90dkQ";alg="ed25519";expires=1794680168;nonce="2ZiaFxZzI1oVzH5V6t3KX9b8rD8hQe1yWmQ0oUeJkW4Bd7nK1Lx3pV9sTq2cR6yA5gHf0jE8uN4mZ7wP1iO3bA";tag="web-bot-auth"
Signature: sig1=:vvB5Hpvp0Iv97Dup9+iHnChRRml7s+Ii8mdwx7f04YIEQPCJ3FPFCpixaE0YWKFfX+y6f8e4PdpqaWVfJw9mAw==:
PartValue
Signature-AgentYour key directory, as a quoted string. Verifiers also accept the working group’s dictionary form (sig1="https://…").
Covered components@authority, signature-agent, @method, @path and @query (? when the URL has none), so neither the address nor the query can be changed in transit. Verifiers check every component a signature lists. The body is not signed.
nonce64 random bytes, base64url, new for every signature. A verifier accepts a nonce once: a request sent again with the same headers is refused, so a retry signs again, as the SDKs do on every call.
keyidThe key’s JWK SHA-256 thumbprint (RFC 7638), base64url.
alged25519, the only algorithm accepted.
created, expiresUnix seconds. The SDKs sign for 60 seconds by default, 5 minutes at most. Pidgeon refuses a signature 30 seconds after its expires, one made more than 5 minutes ago, and one whose created is more than 30 seconds ahead of its clock.
nonce64 random bytes, base64url, new in every signature. Pidgeon accepts a signature once, so a copied request is refused; a retry is signed again. The SDKs do both.
tagweb-bot-auth.

Sign with the SDK

PIDGEON_AGENT_KEY is the private key as JSON (a JWK), PIDGEON_DIRECTORY your directory. The agent’s page gives both.

import { agentFromEnv, signedFetch } from '@pidgeon-ai/sdk';

// From the environment:
const agent = agentFromEnv();
await agent.fetch('https://shop.example/signup', { method: 'POST' });

// Or with a key you hold:
await signedFetch('https://shop.example/signup', { method: 'POST' }, {
  privateJwk,                                  // the agent's private JWK
  directory: 'https://acme.agents.pidgeon.ai',
});

Only the headers

For another HTTP client, get the three headers and add them yourself.

import { signAgentRequest } from '@pidgeon-ai/sdk';

const headers = await signAgentRequest(
  new Request('https://shop.example/signup', { method: 'POST' }),
  { privateJwk, directory: 'https://acme.agents.pidgeon.ai', lifetimeSeconds: 60 },
);
// { 'signature-agent': '"https://…"', signature: 'sig1=:…:', 'signature-input': 'sig1=(…)…' }

Set an agent up from code

Register the agent, make its key where it runs, and publish only the public half. The publishing request is itself signed with the new key: that is how Pidgeon knows you hold it. agents.setUp does all three; it needs a key with admin access.

import { Pidgeon } from '@pidgeon-ai/sdk';

const pidgeon = new Pidgeon({ apiKey: process.env.PIDGEON_API_KEY! }); // admin access
const { agent, key, kid } = await pidgeon.agents.setUp({
  name: 'Booking agent',
  purpose: 'Books tables.',
});
// Keep key.privateJwk where the agent runs, as its PIDGEON_AGENT_KEY,
// and agent.directory as its PIDGEON_DIRECTORY.

A coding agent does the same with the MCP server: set_up_agent keeps the key in a file on your machine and never shows it to the model.

For an agent already registered, make a key and publish it by hand:

import { Pidgeon, generateAgentKey } from '@pidgeon-ai/sdk';

const key = await generateAgentKey(); // { kid, publicJwk, privateJwk }
const pidgeon = new Pidgeon({ apiKey: process.env.PIDGEON_API_KEY! }); // admin access
await pidgeon.publishKey({
  agentId: '<the agent’s id>',
  key,
  directory: 'https://acme.agents.pidgeon.ai',
});
// Keep key.privateJwk as the agent's PIDGEON_AGENT_KEY.

POST /v1/agents

Register an agent identity. Needs admin access; a key of one pod registers in its pod only. name is 1 to 80 characters, purpose up to 280. The answer has the agent’s directory. GET /v1/agents lists them (read), a page at a time.

{ "name": "Booking agent", "purpose": "Books tables." }

GET /v1/agents/{id}

One agent (read): its published keys (public facts only), its directory, and its operator’s reputation in words, { band, seen, next }.

POST /v1/agents/{id}/keys

Needs a key with admin access; a key of one pod publishes only for its pod’s agents. The body is the Ed25519 public JWK, with no private part. The request must carry the signature headers above, made with the key being published.

{ "public_jwk": { "kty": "OKP", "crv": "Ed25519", "x": "dMKP5VcjdGbkRnRofDfKtlHY6Dw_asIbny9W38rai9s" } }
Statuserror.codeWhen
400invalidNo public_jwk, or it is not an Ed25519 public key.
403forbiddenThe request is not signed with this key, or the agent is revoked.
404not_foundNo such agent in this account (or this key’s pod).
409conflictThis key is already published.

Rename and revoke

Each needs a key with admin access; a key of one pod reaches only its pod’s agents, and any other answers 404.

CallDoesAnswers
PATCH /v1/agents/{id}Changes name (1 to 80 characters), purpose (up to 280) or both: what websites see when it arrives.The agent.
DELETE /v1/agents/{id}/keys/{kid}Revokes one key. Its other keys stay. Revoking a revoked key does nothing.204.
DELETE /v1/agents/{id}Revokes the agent and every key it has. It cannot be undone, and a revoked agent publishes no new key.204.
await pidgeon.agents.update(agentId, { name: 'Booking agent' });
await pidgeon.agents.revokeKey(agentId, kid);
await pidgeon.agents.revoke(agentId);

Checking a signature yourself

Checking only the signature is free and needs no call to Pidgeon: fetch the directory named in Signature-Agent, find the key by keyid, and verify. Keep the directory no longer than its Cache-Control says (60 seconds): a key published or revoked reaches you within that. On an unknown keyid, fetch the directory again before refusing, at most once a minute.

import { verifyAgentRequest } from '@pidgeon-ai/sdk';

const result = await verifyAgentRequest(request, async (kid) => findKeyInDirectory(kid));
// { ok: true, kid, directory, created, expires } or { ok: false, reason, detail }