# Accounts, API keys and pods

> One Pidgeon account holds your inboxes, your team, your billing and your reputation. Your servers call the API with an account’s API key, and each key has an access level that decides what it may do. Pods divide an account into tenants, so a platform keeps each user’s inboxes, domains and agents apart.

Source: https://pidgeon.ai/docs/api-keys

## Accounts and the team

- An account is a person’s or a company’s. People sign in by email link or Google.
- The owner invites people by address; nobody joins until they accept, signed in with that address. The owner can withdraw an invitation and remove members; a member can leave. A person belongs to one account. Teams are free.
- The verification level, the reputation and billing belong to the account, never to a member.

## API keys

Make a key in the dashboard, under **API keys** in the menu. It looks like `pgn_` and 32 characters, and it is shown once: Pidgeon keeps only its SHA-256. Send it as a bearer token, from a server, never from a browser or an app.

```bash
curl https://pidgeon.ai/v1/pods -H "Authorization: Bearer $PIDGEON_API_KEY"
```

### Access levels

Each level includes the ones before it. A key below what a call needs gets `403 forbidden`, naming the level.

| Access | May | For example |
| --- | --- | --- |
| `read` | Look | Every `GET`: inboxes, mail, conversations, events. |
| `draft` | Prepare without effect | Writing Email drafts and asking a person to approve them; never sending. |
| `send` | Act on somebody else | Sending mail, mandates. |
| `admin` | Change the account’s setup | Inboxes, domains, pods, webhooks, agent keys, sites. |

The dashboard offers all four: **Read**, **Draft**, **Send** and **Admin**. Revoke a key in the same place; it stops at once.

### Keys from the API

An agent setting Pidgeon up can make its own keys: `POST /v1/keys` with an `admin` key of the whole account (or the MCP server’s `create_api_key`). A new key is never stronger than the one making it, and a test key makes only test keys. The key is in the answer once: put it straight where it will live. `GET /v1/keys` lists them without the keys; `DELETE /v1/keys/{id}` revokes one.

```bash
curl https://pidgeon.ai/v1/keys \
  -H "Authorization: Bearer $PIDGEON_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support agent", "access": "draft"}'
```

### Test keys

Choose **Test** as the mode when you make a key, and it looks like `pgn_test_` and 32 characters. A test key does everything a live key does, except where it is marked test:

- None of its mail leaves Pidgeon. See [mail that never leaves](https://pidgeon.ai/docs/email.md#test-mode).
- A mandate it asks for is a test mandate: it needs no verified domain, and every token under it says `test: true`, for a site to refuse in production. See [testing mandates](https://pidgeon.ai/docs/mandates.md#testing).

Use one in CI, in staging, or wherever an agent is being built.

### Rate limit

600 requests a minute per key, over a sliding window. Past it: `429 rate_limited` with `Retry-After` in seconds.

Every answer to a key says where it stands, in the IETF fields `RateLimit-Policy` and `RateLimit` (draft-ietf-httpapi-ratelimit-headers) and in the older `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` most clients read:

Headers:

```http
RateLimit-Policy: "per-key";q=600;w=60
RateLimit: "per-key";r=597;t=42
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42
```

`r` and `RateLimit-Remaining` are the requests left; `t` and `RateLimit-Reset` the seconds until the window refills. Sending has limits of its own, per account: [sending limits](https://pidgeon.ai/docs/sending.md#limits).

### Idempotency

A call that sends mail or makes something takes an `Idempotency-Key` header, so a retry after a timeout or a dropped connection is never done twice: `POST /v1/email/inboxes/{id}/messages`, `POST /v1/email/drafts/{id}/send`, `POST /v1/email/inboxes/{id}/drafts`, `POST /v1/email/inboxes` and `POST /v1/pods`.

- The key is any 1 to 255 printable characters unique to the request: a UUID, or your own id for the message.
- The first call with a key is done, and its answer kept 24 hours. A retry with the same key and the same body, from the same API key, gets that answer again, with `Idempotent-Replayed: true`, and nothing is sent or made.
- The same key with a different body, or from another key of the account, is `422 idempotency_key_reused`. A retry while the first call is still running is `409 idempotency_in_progress`, with `Retry-After`.
- An answer of `429` or `5xx` is not kept, since nothing was done: retry with the same key.

## Pods

A pod is a tenant inside an account: a platform gives one to each of its users ([Platforms](https://pidgeon.ai/docs/platforms.md)). Inboxes, domains, agents, sign-in sites and webhook endpoints each live in one. Every account has a default pod, which is where anything made without a `pod_id` goes. Billing, the team, KYB and reputation stay with the account.

A key of one pod reaches only its own pod: its agents, inboxes, domains, webhook endpoints and events. It makes inboxes on, and sends from, its own pod’s domains and `pidgeon.email` only, so one customer’s pod never mails as another’s domain.

curl:

```bash
# List (read access)
curl https://pidgeon.ai/v1/pods -H "Authorization: Bearer $PIDGEON_API_KEY"

# Create (admin access, a key of the whole account)
curl https://pidgeon.ai/v1/pods \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer: Northwind"}'

# Rename (admin access, a key of the whole account)
curl -X PATCH https://pidgeon.ai/v1/pods/1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6 \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer: Northwind Labs"}'

# Move an agent (with its addresses and their mail) into a pod
curl https://pidgeon.ai/v1/pods/1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6/move \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "agent", "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a"}'

# Remove an empty pod (admin access, a key of the whole account)
curl -X DELETE https://pidgeon.ai/v1/pods/1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6   -H "Authorization: Bearer $PIDGEON_API_KEY"
```

Response:

```json
{
  "data": [
    { "id": "7c6b5a49-3827-4161-9f0e-d1c2b3a49586", "name": "Default", "default": true,
      "created_at": "2026-11-13T09:12:44.512Z" },
    { "id": "1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6", "name": "Customer: Northwind", "default": false,
      "created_at": "2026-11-14T12:00:00.000Z" }
  ]
}
```

A pod’s name is up to 80 characters and unique in the account. Pass `pod_id` when registering an agent or creating an inbox or an Auth site to put it in a pod. Renaming one (`PATCH`, `name`) answers the pod and records `pod.renamed`; its id and everything in it stay. `POST /v1/pods/{id}/move` with `type` (`agent`, `inbox`, `domain`, `webhook` or `site`) and `id` (a site’s client id) moves that thing into the pod and records `pod.item_moved`: an agent takes its addresses and all their mail with it, and an address that belongs to an agent moves only with it (`409`). API keys do not move: a key’s reach is chosen when it is made. Keys of the pod a thing left stop reaching it. Moving takes an admin key of the whole account. Removing a pod answers `204` and records `pod.removed`; the default pod cannot be removed (`403`), and a pod with agents, domains or webhook endpoints in it answers `409` until they are removed.

### Keys of one pod

A key can reach one pod instead of the whole account: it then makes inboxes, reads and sends their mail, adds webhook endpoints, lists events, publishes and revokes agent keys and makes sites only within that pod, and cannot make or remove pods or make keys.

In the dashboard, Account → Pods lists the account’s pods, and its owner makes, renames and removes them there. Once there are two, a switcher at the top shows one pod or all, and making a key asks what it reaches: the whole account, or one pod.

### Keys of some inboxes

A key from the old Pidgeon that reached only some addresses reaches only those inboxes here. It lists and reads their mail, conversations and events, and sends from them; every other call answers `401`. Keys made in the dashboard reach the whole account.

## Apps that connect with OAuth

An app can ask a person for access instead of an API key, by the authorization code flow with PKCE. The authorization server’s metadata is at `/.well-known/oauth-authorization-server`; apps identify themselves with a client metadata document (an https `client_id`) or register at `/oauth/register` (RFC 7591). The person chooses the access level on the consent screen, never more than the app asked for (the scopes are `read`, `draft`, `send`, `admin`).

- Access tokens are `pgn_oat_…`, for an hour, and work on `/v1` like the API key they stand for.
- Refresh tokens are `pgn_ort_…` and turn over on every use; one used twice ends the connection. An app registered as an Auth site sends its client secret with the refresh, as at the code exchange.
- **Connected apps**, in the dashboard’s menu, lists them and disconnects them. `POST /oauth/revoke` ends one from the app’s side.
- Every `401` from `/v1` carries `WWW-Authenticate: Bearer resource_metadata="https://pidgeon.ai/.well-known/oauth-protected-resource"`.
