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

Source: https://pidgeon.ai/docs/mandates

## 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](https://pidgeon.ai/docs/passport.md#verify-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](#testing).

curl:

```bash
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
  }'
```

Response 201:

```json
{
  "id": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
  "agent_id": "0b6d1c5e-8f2a-4e7b-9c1d-2a3b4c5d6e7f",
  "account_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "client_id": "site_q8Zr2mX4k1Vb7nPw0sTe",
  "scope": "orders:write",
  "description": "Book and pay for train tickets on your Shop Example account.",
  "status": "requested",
  "user_id": null,
  "test": false,
  "expires_at": "2026-12-14T11:40:00.000Z",
  "created_at": "2026-11-14T11:40:00.000Z",
  "consent_url": "https://pidgeon.ai/auth/mandate/…",
  "request_expires_at": "2026-11-21T11:40:00.000Z"
}
```

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](#stopping)).

## 3. The agent signs in as the person

The same signed [token exchange](https://pidgeon.ai/docs/auth-agents.md#token-exchange), with the mandate’s id and its type. Any live key of the mandate’s agent may sign.

Form:

```text
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_q8Zr2mX4k1Vb7nPw0sTe
```

ID token claims:

```json
{
  "iss": "https://pidgeon.ai",
  "sub": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "aud": "site_q8Zr2mX4k1Vb7nPw0sTe",
  "kind": "agent",
  "account": { "name": "Acme GmbH", "slug": "acme", "verification": "kyb" },
  "agent": { "name": "Acme booking agent", "purpose": "Books train tickets for Acme's customers", "directory": "https://acme.agents.pidgeon.ai" },
  "reputation": "good",
  "pod": "7c6b5a49-3827-4161-9f0e-d1c2b3a49586",
  "act": {
    "sub": "0b6d1c5e-8f2a-4e7b-9c1d-2a3b4c5d6e7f",
    "agent": { "name": "Acme booking agent", "purpose": "Books train tickets for Acme's customers", "directory": "https://acme.agents.pidgeon.ai" },
    "account": { "name": "Acme GmbH", "slug": "acme", "verification": "kyb" },
    "reputation": "good"
  },
  "mandate": {
    "id": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d",
    "scope": "orders:write",
    "expires_at": "2026-12-14T11:40:00.000Z"
  },
  "scope": "orders:write",
  "cnf": { "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "…" } }
}
```

- `sub` is the person (the same id their own sign-in gives you); `act` is 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 `cnf` as for any [agent sign-in](https://pidgeon.ai/docs/auth-agents.md#site-side).

> **Note:** The SDKs’ `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.

TypeScript:

```ts
const claims = await verifyAgentSignIn(request, {
  clientId: 'site_q8Zr2mX4k1Vb7nPw0sTe',
  clientSecret: process.env.PIDGEON_CLIENT_SECRET,
});
// A stopped mandate: SignInError, reason 'mandate_ended'.
```

Python:

```python
claims = verify_agent_sign_in(request.method, str(request.url), request.headers,
                              "site_q8Zr2mX4k1Vb7nPw0sTe",
                              client_secret=os.environ["PIDGEON_CLIENT_SECRET"])
# A stopped mandate: SignInError, reason "mandate_ended".
```

curl:

```bash
curl https://pidgeon.ai/oauth/introspect \
  -u "site_q8Zr2mX4k1Vb7nPw0sTe:$PIDGEON_CLIENT_SECRET" \
  -d "token=$ID_TOKEN"
```

Response 200:

```json
{
  "active": true,
  "client_id": "site_q8Zr2mX4k1Vb7nPw0sTe",
  "sub": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "exp": 1794683600,
  "iat": 1794683000,
  "iss": "https://pidgeon.ai",
  "mandate": { "id": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "status": "granted" }
}
```

A wrong client id or secret answers `401` `invalid_client`.

## Testing

Ask with a [test key](https://pidgeon.ai/docs/api-keys.md#test-keys) (`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 no `test` claim.
- 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 (`403` without it).

> **Note:** A site should refuse a token with `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.

TypeScript:

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

Python:

```python
claims = verify_agent_sign_in(request.method, str(request.url), request.headers,
                              client_id, client_secret=client_secret)
if claims.get("test") and PRODUCTION:
    raise PermissionError("Test mandates are not accepted here.")
```

## 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](#testing). |
| 404 | `not_found` | No such agent in this account, or no site with that client id. |
