Grants

List an address’s grants

get/api/v1/grants

Every grant asked for or given to one address, newest first.

Parameters

• identity_iduuidrequired

Responses

• 200The grants.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.

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

Generated · public/openapi.json

Ask for a grant

post/api/v1/grants

A grant says what an agent may do, for whom, until when, signed by us and checkable by anyone at `POST /verify`. With `grantor: { email }`, the person is asked: the answer is `pending` and carries `consent_url`, the page to send them to, where they allow it from a link we email them or signed in as that address. Nothing is signed until they do. With `grantor: { organisation: true }` the account grants at once, as its verified domain, which needs a live key with admin on the account. Either way it needs `send` on the address. Carry an active grant with `grant_ids` on `POST /messages`.

Parameters

• Idempotency-Keystring

  Any string unique to this attempt, reused on its retries. A repeat with the same key and the same request returns the first answer with `Idempotent-Replay: true` and does nothing — no second email. The same key with a different request is a `409`. Kept for 24 hours; a failure is not kept, so a retry after one runs.

Body

• identity_iduuidrequired

  The agent’s address.

• templatestringrequired

  A template’s `name` or `id`.

• grantorobjectrequired

  `{ email }` asks that person on a consent page, and the answer carries `consent_url` to send them to. `{ organisation: true }` grants at once as this account’s verified domain, and needs a key with admin on the account.

• subject_idstringrequired

  The customer, account or order it is for, in the recipient’s own terms.

• expires_atdate-time

  When it ends. The template’s `max_days` from now when omitted, and at most that.

Responses

• 201The grant.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409Nothing was done by this call. `error.code` says which: `idempotency_in_progress` when the first request with this `Idempotency-Key` has not answered yet (wait `Retry-After` seconds and send it again), `idempotency_mismatch` when the key was used with a different request (use a new key).
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.
• 504Test mode only: `Pidgeon-Test-Fail: drop` dropped the answer (`test_dropped`). The request was done; retry it with the same `Idempotency-Key` to get the first answer.

curl https://pidgeon.ai/api/v1/grants \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Read a grant

get/api/v1/grants/{id}

Its status and, while active, `jws`: the signed grant the agent carries.

Parameters

• idstringrequired

Responses

• 200The grant.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.

curl https://pidgeon.ai/api/v1/grants/{id} \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Revoke a grant

delete/api/v1/grants/{id}

For good, at once: the next `POST /verify` says `revoked`. A pending one stops its consent link working. Needs `send` on the address.

Parameters

• idstringrequired
• Idempotency-Keystring

  Any string unique to this attempt, reused on its retries. A repeat with the same key and the same request returns the first answer with `Idempotent-Replay: true` and does nothing — no second email. The same key with a different request is a `409`. Kept for 24 hours; a failure is not kept, so a retry after one runs.

Responses

• 200The grant, revoked.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409Nothing was done by this call. `error.code` says which: `idempotency_in_progress` when the first request with this `Idempotency-Key` has not answered yet (wait `Retry-After` seconds and send it again), `idempotency_mismatch` when the key was used with a different request (use a new key).
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.
• 504Test mode only: `Pidgeon-Test-Fail: drop` dropped the answer (`test_dropped`). The request was done; retry it with the same `Idempotency-Key` to get the first answer.

curl https://pidgeon.ai/api/v1/grants/{id} \
  -X DELETE \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Whether a grant still holds

get/api/v1/grants/{id}/status

Public, with no key: the URL every grant names as its `status`, for a recipient that checks a grant’s signature offline. `active`, `revoked` or `expired`. Cached thirty seconds, so a revocation shows within the minute. `POST /verify` reads the grant itself and needs none of this. A grant never given answers 404.

Parameters

• idstringrequired

Responses

• 200Its status.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.

curl https://pidgeon.ai/api/v1/grants/{id}/status \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json