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", "permissions": ["campaigns:read", "campaigns:send"], "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.

permissions takes values from the permissions catalogue below. Grant only what the integration needs. A key that calls an endpoint outside its permissions is refused with 403 INSUFFICIENT_SCOPE.

Available permissions

GET /api-keys/permissions

Returns the complete catalogue of permissions the API accepts. It is generated from the same definitions the API checks against, so it is always current. Read the values from here rather than hard-coding a list.

{
  "resources": [
    {
      "resource": "campaigns",
      "label": "Campaigns",
      "group": "Messaging",
      "wildcard": "campaigns:*",
      "covers": ["/campaigns"],
      "actions": [
        { "action": "read",  "label": "Read",  "value": "campaigns:read" },
        { "action": "write", "label": "Write", "value": "campaigns:write" },
        { "action": "send",  "label": "Send",  "value": "campaigns:send" }
      ]
    }
  ],
  "wildcards": [
    { "action": "*",    "label": "Full access to everything",     "value": "*:*" },
    { "action": "read", "label": "Read-only access to everything", "value": "*:read" }
  ],
  "presets": [
    { "preset": "full",      "label": "Full access", "values": ["*:*"] },
    { "preset": "read_only", "label": "Read-only",   "values": ["*:read"] }
  ]
}

• value is the exact string to send in permissions. Use it verbatim rather than joining resource and action yourself.
• wildcard grants every action on that resource; covers lists the API paths the resource governs.
• presets are ready-made sets for the common cases.

For how an endpoint's required permission is determined, and the shape of a refusal, see Authentication → Permissions.

Update

PUT /api-keys/{id}
{ "name?": "...", "permissions?": ["campaigns:read"], "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.