Authentication

Every request carries an API key as a bearer token. Keys are account-wide, server-side only, and never valid in a browser — a key in client JavaScript is a key anyone who opens devtools now owns.

curl https://pidgeon.ai/api/v1/identities -H "Authorization: Bearer $PIDGEON_API_KEY"

What a key can reach

Everything the account owns, narrowed by each address's own capabilities. Capabilities are derived from the address's type and the plan rather than stored, so they cannot drift from what the product shows: an application address has no inbox, and asking for its threads returns nothing rather than an error.

There is no per-address key and no read-only key yet. When there is, it will be listed on the plans the day it works.

The SDK

@pidgeon-ai/sdk is a thin typed client over exactly these endpoints, plus the webhook verifier. It sets the header, parses the envelope, and turns a failure into a PidgeonError carrying the same code the API returned — nothing else, which is why it is worth using.

npm install @pidgeon-ai/sdk

Every TypeScript sample in these docs is written against it. The cURL and Python samples are the same calls without one, so nothing here is only reachable through a package.

Rotating

Create the new key, deploy, delete the old one. There is no expiry and no grace window, because a key that stops working on a schedule nobody remembers is an outage with a calendar invite.

A deleted key stops working immediately. The event log keeps which key made which call, so a key you are unsure about can be answered rather than guessed at.

Idempotency

Any POST accepts an Idempotency-Key header. The same key with the same body returns the first response rather than doing the work twice; the same key with a different body is an error, because that is a bug in the caller rather than a retry.

curl https://pidgeon.ai/api/v1/messages -H "Authorization: Bearer $PIDGEON_API_KEY" -H "Idempotency-Key: 8f21c-invoice-4417" -H "Content-Type: application/json" -d '{ "from": "hello@yourdomain.com", "to": "a@example.com", "text": "Hi" }'