Search the docs

Find a page, a section, or an endpoint.

Sign inGet started

api-keys

Every api-keys endpoint, generated from the API's own schemas.

List the keys in this workspace

get/api/v1/api-keys

Names, prefixes, what each reaches and when it was last used — never a secret. The list is what you read before revoking something.

Responses

  • 200A page of keys.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/api-keys \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json

Mint a key

post/api/v1/api-keys

`identity_ids` is required and must be a subset of what the calling key already reaches: a key cannot delegate reach it does not have. The `token` is in this response and nowhere else, ever.

Body

  • namestringrequired
  • identity_idsuuid[]required

Responses

  • 201The key, with its token.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Revoke a key, and everything it minted

delete/api/v1/api-keys/{id}

Transitive, and that is the point: a leaked key would otherwise mint a second one and survive its own rotation. A key may revoke itself and keys it made — not a sibling, and not its parent.

Parameters

  • idstringrequired

Responses

  • 200Revoked.
  • 401No API key, or one that is not valid.
  • 404No such resource, **or** one belonging to another account. The two are deliberately indistinguishable: a different answer would enumerate what exists.
  • 429Rate limited. `X-RateLimit-Reset` says when to retry.
bash
curl https://pidgeon.ai/api/v1/api-keys/{id} \
  -X DELETE \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json