# 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.

Source: https://pidgeon.ai/docs/signing-requests

## What a signed request carries

HTTP:

```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==:
```

| Part | Value |
| --- | --- |
| `Signature-Agent` | Your 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. |
| `nonce` | 64 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. |
| `keyid` | The key’s JWK SHA-256 thumbprint (RFC 7638), base64url. |
| `alg` | `ed25519`, the only algorithm accepted. |
| `created`, `expires` | Unix 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. |
| `nonce` | 64 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. |
| `tag` | `web-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.

TypeScript:

```ts
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',
});
```

Python:

```python
import httpx
from pidgeon import agent_from_env, signed_client, AgentAuth

# From the environment:
with agent_from_env().client() as http:
    http.post("https://shop.example/signup")

# Or with a key you hold:
http = signed_client(private_jwk, "https://acme.agents.pidgeon.ai")

# Or on an httpx client you already have, sync or async:
client = httpx.Client(auth=AgentAuth(private_jwk, "https://acme.agents.pidgeon.ai"))
```

### Only the headers

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

TypeScript:

```ts
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=(…)…' }
```

Python:

```python
from pidgeon import sign_request

headers = sign_request("POST", "https://shop.example/signup", None,
                       private_jwk, "https://acme.agents.pidgeon.ai")
```

## 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.

TypeScript:

```ts
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.
```

Python:

```python
import os
from pidgeon import Pidgeon

pidgeon = Pidgeon(api_key=os.environ["PIDGEON_API_KEY"])  # admin access
made = pidgeon.agents.set_up("Booking agent", "Books tables.")
# Keep made.key.private_jwk where the agent runs; made.agent["directory"] is its directory.
```

CLI:

```bash
npm install -g @pidgeon-ai/cli
pidgeon login
pidgeon agents create "Booking agent" --purpose "Books tables."
# The key is kept in ~/.config/pidgeon/agents/<id>.json, readable by you only.
```

A coding agent does the same with the [MCP server](https://pidgeon.ai/docs/sdks.md#mcp): `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:

TypeScript:

```ts
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.
```

Python:

```python
import os
from pidgeon import Pidgeon, generate_agent_key

key = generate_agent_key()  # key.kid, key.public_jwk, key.private_jwk
Pidgeon(api_key=os.environ["PIDGEON_API_KEY"]).publish_key(
    "<the agent’s id>", key, "https://acme.agents.pidgeon.ai")
```

### 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.

Request:

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

Response 201:

```json
{
  "id": "6f1c2a9e-3b7d-4c55-9a0e-2d8b1f4e7c31",
  "name": "Booking agent",
  "purpose": "Books tables.",
  "status": "active",
  "pod_id": "0d9e8f7a-…",
  "created_at": "2026-11-14T10:00:00Z",
  "revoked_at": null,
  "directory": "https://acme.agents.pidgeon.ai"
}
```

### GET /v1/agents/{id}

One agent (`read`): its published keys (public facts only), its directory, and its operator’s [reputation](https://pidgeon.ai/docs/reputation.md) 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.

Request:

```json
{ "public_jwk": { "kty": "OKP", "crv": "Ed25519", "x": "dMKP5VcjdGbkRnRofDfKtlHY6Dw_asIbny9W38rai9s" } }
```

Response 201:

```json
{ "kid": "KUqU0uc-fPnz0RGiU5gdnMXYaa6FUqqDKcy-oa90dkQ" }
```

| Status | `error.code` | When |
| --- | --- | --- |
| 400 | `invalid` | No `public_jwk`, or it is not an Ed25519 public key. |
| 403 | `forbidden` | The request is not signed with this key, or the agent is revoked. |
| 404 | `not_found` | No such agent in this account (or this key’s pod). |
| 409 | `conflict` | This 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`.

| Call | Does | Answers |
| --- | --- | --- |
| `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`. |

TypeScript:

```ts
await pidgeon.agents.update(agentId, { name: 'Booking agent' });
await pidgeon.agents.revokeKey(agentId, kid);
await pidgeon.agents.revoke(agentId);
```

Python:

```python
pidgeon.agents.update(agent_id, name="Booking agent")
pidgeon.agents.revoke_key(agent_id, kid)
pidgeon.agents.revoke(agent_id)
```

CLI:

```bash
pidgeon agents rename <agent-id> "Booking agent"
pidgeon keys revoke <agent-id> <kid>
pidgeon agents revoke <agent-id>
```

## 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.

TypeScript:

```ts
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 }
```

Python:

```python
from pidgeon import verify_agent_request

result = verify_agent_request(method, url, headers, find_key)  # find_key(kid) -> JWK or None
```
