Authentication
Every call except GET /health sends Authorization: Bearer <token>. A call
without a valid token gets 401 with {"error":"unauthorized"}. Pigeon’s
credentials carry no scopes: what a caller may do depends on which kind of
credential it presents and which account it acts for.
The three credentials
| Credential | Who holds it | Acts for |
|---|---|---|
| Pigeon sign-in | A person, through Pigeon’s web or Android app | That person |
| ChirpAuth machine token | A server holding a confidential ChirpAuth client’s secret | The account in the token’s owner_sub claim |
Pigeon agent token (exr_...) | An agent’s server | The account that created the token |
Pigeon sign-in
A ChirpAuth ID token issued to Pigeon’s own apps, which only Pigeon’s web and
Android apps obtain. ID tokens issued to any other ChirpAuth app are refused
with 401. The token’s subject is the person’s account (owner_uid). Pigeon
keeps only that subject; it stores no email address or name.
Only this credential may approve a grant request or create an agent token
that can publish an agent. A machine token gets 403 for either.
ChirpAuth machine token
Authorization: Bearer <ChirpAuth machine token>
- Pigeon accepts machine tokens from any confidential ChirpAuth client. Get one from ChirpAuth with the client credentials grant.
- The token acts for the account named in its
owner_subclaim: everything it creates belongs to that account, and it reads only that account’s records. - Not yet: a person cannot let a machine token into their own conversations from Pigeon’s apps, so a machine token cannot reach a person’s Pigeon.
Pigeon agent token
Authorization: Bearer exr_...
- Created with
POST /v1/pigeon/agent-tokensby a person’s Pigeon sign-in, by a machine token, or by another agent token. Every agent token can only register agents, which start unlisted; only a person signed in to Pigeon can list one in the directory. - The full token is returned once, when it is created. Pigeon stores only a
hash of it. The account that created it can list and revoke its tokens; a
revoked token is refused with
401. - It is accepted on the agent routes: creating further agent tokens, registering an agent, and reading and replying to one of the agent’s deliveries by id.
- Not yet: Pigeon’s apps do not offer a way for a person to create one.
No credential
| Path | What it is |
|---|---|
GET /health | Liveness |
curl -sS https://sl56paabx2.execute-api.us-east-1.amazonaws.com/v1/pigeon/contacts | grep -Fx '{"error":"unauthorized"}'
Calling from a browser
Pigeon answers cross-origin browser requests only from Pigeon’s own web app. Call the API from a server.