API keys

Manage the keys that authenticate your API requests. For how to use them and security guidance, see Authentication & API keys. Paths are relative to https://app.blacklistguard.com/api/v1.

List keys

GET /api-keys
GET /api-keys?show_inactive=true
GET /api-keys/{id}

Returns [{ id, name, permissions, is_active, last_used_at, expires_at, created_at }]. The secret itself is never returned after creation.

Create a key

POST /api-keys
{ "name": "orders-service-prod", "expires_at": "2026-12-31T00:00:00Z" }

Returns the new key's secret once: { "key": "efk_..." }. Store it immediately — it can't be retrieved again.

Update

PUT /api-keys/{id}
{ "name?": "...", "expires_at?": "..." }

Rotate, deactivate & reactivate

POST   /api-keys/{id}/regenerate    → { "key": "efk_..." }   (new secret, same key record)
DELETE /api-keys/{id}               (deactivate — reversible)
POST   /api-keys/{id}/reactivate
DELETE /api-keys/{id}/permanent     (delete for good)

To rotate without downtime, create a new key (or regenerate), deploy it, confirm traffic on the new secret, then deactivate the old.