Sign in with Pidgeon
Mandates
A mandate lets a person authorise one of your agents to act for them at one site, for a scope and until a date. You ask with POST /v1/auth/mandates and send the person the consent link; once they allow it, the agent signs in to that site as the person, with itself named as the actor.
1. Ask for a mandate
Needs an API key with send access. The agent must be your own and active, with at least a verified domain behind it (verify a domain). The site must be registered with Sign in with Pidgeon. To try mandates before you have a domain, ask with a test key: see testing.
curl https://pidgeon.ai/v1/auth/mandates \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "0b6d1c5e-8f2a-4e7b-9c1d-2a3b4c5d6e7f",
"client_id": "site_q8Zr2mX4k1Vb7nPw0sTe",
"scope": "orders:write",
"description": "Book and pay for train tickets on your Shop Example account.",
"days": 30
}'While the mandate is requested, expires_at is where it would end if allowed now. Allowing it sets expires_at to days from that moment, so a person who answers on day six still gets the full days.
| Field | Value |
|---|---|
agent_id | Your agent. |
client_id | The site, as registered with Sign in with Pidgeon. |
scope | What the site lets the agent do, in the site’s words. Up to 500 characters. |
description | One sentence the person reads. Up to 280 characters. |
days | How long it lasts once granted, counted from the moment the person allows it: 1 to 90. Default 30. |
2. The person decides
Send the person consent_url. It works once, for seven days. They open it signed in to Pidgeon (anyone can sign up) and allow or decline. The page names the site as it registered with Sign in with Pidgeon, the agent and what it is for, who runs it and their reputation, your description, the site’s scope, how long it lasts, and which Pidgeon account the person is signed in as. Auth, under Mandates shows what they allowed and lets them stop it at any time (stopping it).
3. The agent signs in as the person
The same signed token exchange, with the mandate’s id and its type. Any live key of the mandate’s agent may sign.
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d
&subject_token_type=urn:pidgeon:params:oauth:token-type:mandate
&audience=site_q8Zr2mX4k1Vb7nPw0sTesubis the person (the same id their own sign-in gives you);actis the agent (RFC 8693 §4.1).- The person’s email is never in it.
- It works only for the mandate’s site, only while granted and unexpired. Check the request’s signature against
cnfas for any agent sign-in.
Note
signInAsAgent sends the agent-key type only. Under a mandate, send this form yourself, signed with signAgentRequest.Stopping it
The person stops a mandate in Auth, under Mandates; you stop it with DELETE /v1/auth/mandates/{id}. From that moment the agent gets no new token under it: the exchange answers invalid_grant. A mandate that reaches expires_at stops the same way.
An ID token already issued cannot be recalled. It is signed, and good until its exp: at most ten minutes after it was issued, so up to ten minutes after the mandate stopped. A site that checks only the token accepts it for that long.
To close that window, ask Pidgeon. POST /oauth/introspect (RFC 7662), authenticated as your site with its client id and secret by HTTP Basic, with the token as token, answers {"active": true} only while the token is good and its mandate still holds; {"active": false} otherwise, and for a token issued to another site. The SDKs do it when you pass your secret, only for tokens under a mandate: one request to Pidgeon per check.
const claims = await verifyAgentSignIn(request, {
clientId: 'site_q8Zr2mX4k1Vb7nPw0sTe',
clientSecret: process.env.PIDGEON_CLIENT_SECRET,
});
// A stopped mandate: SignInError, reason 'mandate_ended'.A wrong client id or secret answers 401 invalid_client.
Testing
Ask with a test key (pgn_test_…) and the mandate is a test mandate, "test": true. It needs no verified domain behind the agent, so you can try the whole flow before you own one: ask, allow it yourself, sign in as the agent, verify at your site. Only a member of your own account can allow it: anyone else who opens the link is told it is a test and to ask you for a live mandate, and an answer from them is refused (forbidden). Everything else is as for a live mandate: the consent link, the days, stopping it, introspection.
- The consent page opens with This is a test: nobody has proved who runs the agent, and the site is told. It opens only for your account’s members.
- Every ID token exchanged under it carries
"test": true, and so does introspection’s answer. A token under a live mandate has notestclaim. - Agents and their keys have no mode of their own: the mandate’s mode, set by the key that asked for it, is the token’s. A test key cannot make a live mandate, and a live mandate’s tokens never say test.
- With a live key the verified domain is still needed (
403without it).
Note
test: true in production, as it would any sign-in nobody vouches for: check claims.test after verifying it. The SDKs verify test tokens as they do live ones, so your own staging can test end to end.const claims = await verifyAgentSignIn(request, { clientId, clientSecret });
if (claims.test && process.env.NODE_ENV === 'production') {
return new Response('Test mandates are not accepted here.', { status: 403 });
}List and revoke
| Call | Access | Answers |
|---|---|---|
GET /v1/auth/mandates | read | {data: [mandate…]}, newest first, up to 100. status: requested, granted, declined or revoked; test: asked with a test key. |
DELETE /v1/auth/mandates/{id} | send | 204. Ends a mandate, asked or granted. A key of one pod ends only its pod’s agents’ mandates (404 otherwise). |
Errors
| Status | error.code | When |
|---|---|---|
| 400 | invalid | A field is missing or too long, or days is outside 1–90. |
| 403 | forbidden | The agent is revoked, or the account has no verified domain and the key is live. To try mandates without one, ask with a test key. |
| 404 | not_found | No such agent in this account, or no site with that client id. |