Reference
Open standards
Pidgeon speaks published standards wherever one exists, so any compatible library can sign, verify or sign in without our SDK. This page lists each standard, where Pidgeon uses it, and the few pieces Pidgeon defines itself.
What Pidgeon speaks
| Standard | Where |
|---|---|
| HTTP Message Signatures (RFC 9421) | Every signed agent request: Sign requests. |
| Web Bot Auth (draft-ietf-webbotauth-httpsig-protocol) | The profile on top: Ed25519, tag="web-bot-auth", Signature-Agent, and the key directory at /.well-known/http-message-signatures-directory. Cloudflare’s open-source web-bot-auth package does the signing and checking. |
| Hosted directories (draft-singh-webbotauth-hosted-directories) | One directory per operator at https://<slug>.agents.pidgeon.ai; Pidgeon never holds a private key and checks possession before publishing one; a 300-second cache. |
| JWK thumbprints (RFC 7638) | A key’s id, keyid. |
| OpenID Connect, with Discovery | Sign in with Pidgeon for people: People. |
| OAuth 2.0 (RFC 6749), PKCE (RFC 7636) | The code flow, S256 only. |
| Token Exchange (RFC 8693) | Agents signing in, and act under a mandate: Agents, Mandates. |
| Proof-of-possession (RFC 7800) | cnf.jwk in an agent’s ID token. |
| ID-JAG (draft-ietf-oauth-identity-assertion-authz-grant) | Agents reaching MCP servers that trust Pidgeon: ID-JAG. |
| OAuth metadata (RFC 8414, RFC 9728), registration (RFC 7591), revocation (RFC 7009), resource indicators (RFC 8707) | Apps connecting to the API: Apps that connect with OAuth. |
| Agent attribution headers (draft-chuang-agent-attribution-header-fields) | Agent-of and Agent-attribution on mail from an inbox linked to an agent identity: Send mail. |
| One-click unsubscribe (RFC 8058) | The emails Pidgeon sends to people. |
Compatibility notes
- Ed25519 only. Cloudflare accepts nothing else for Web Bot Auth, so neither does Pidgeon.
- `Signature-Agent` as a string. The working-group draft writes it as a dictionary (
sig1="https://…"); Cloudflare still requires the string form ("https://…"). The SDKs send the string; Pidgeon’s verifier accepts both. - Revocation. Web Bot Auth has none. Pidgeon removes a revoked key from the directory at once, and directories may be cached for 60 seconds (
Cache-Control: max-age=60, never by Pidgeon’s CDN).
What Pidgeon defines
Only what the standards leave open. Each is listed here, so you can implement it without our code.
| Piece | Definition |
|---|---|
urn:pidgeon:params:oauth:token-type:agent-key | A token-exchange subject type: subject_token is a key id, and the request must be signed with that key under Web Bot Auth. |
urn:pidgeon:params:oauth:token-type:mandate | A subject type: subject_token is a mandate id; the request is signed with a key of the mandate’s agent. |
| ID token claims | kind (person or agent), account (name, slug, verification), agent (name, purpose), reputation, pod, mandate. |
Agent-attribution members | issuer, agent, operator, directory (the draft defines none). |
| Webhook signatures | Pidgeon-Signature: t=…,v1=…, HMAC-SHA256: Webhooks. |