API keys

Create, list, rename and revoke API keys programmatically. Keys are shown once on creation and stored only as a hash.

These endpoints need a full-access key

A sending key gets permission_denied here - that's deliberate, so a leaked sending key can't mint more keys. See API keys.

Create a key

POST /v1/api-keys

curl -X POST https://api.sendpository.com/v1/api-keys \
  -H "Authorization: Bearer $SENDPOSITORY_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production", "permission": "sending" }'

Field	Type	Required	Notes
`name`	string	Yes	Up to 60 characters.
`permission`	string	No	`sending` (default) or `full_access`.

{
  "id": "6aec350b-6458-4171-aa2c-ebf5a594d14f",
  "name": "production",
  "permission": "sending",
  "token": "sp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-08-30T09:00:00.000Z"
}

This is the only time you see the token

Store it immediately. We keep only a hash - it can't be recovered, only rotated.

List keys

GET /v1/api-keys

Tokens are masked to their prefix.

{
  "data": [
    {
      "id": "6aec350b-...",
      "name": "production",
      "token": "sp_xxxxxxxx...",
      "permission": "sending",
      "last_used_at": "2026-08-30T09:04:11.882Z",
      "revoked_at": null,
      "created_at": "2026-08-30T09:00:00.000Z"
    }
  ],
  "limit": 25,
  "offset": 0
}

Supports ?limit= (1–100) and ?offset=.

Retrieve a key

GET /v1/api-keys/{id}

Same shape as one entry above.

Rename a key

PATCH /v1/api-keys/{id}

The name is all that's mutable.

curl -X PATCH https://api.sendpository.com/v1/api-keys/{id} \
  -H "Authorization: Bearer $SENDPOSITORY_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production (eu)" }'

A token never changes. To rotate, create a new key and revoke the old one.

Revoke a key

DELETE /v1/api-keys/{id}

{ "id": "6aec350b-...", "revoked": true }

Revokes rather than deletes, so request logs referencing the key keep their meaning. Takes effect on the next request.

A key can't revoke itself

Use another key, or the dashboard. Otherwise a mistake would lock you out of the very endpoint you need.