Get started

Authentication & API keys

Every request to the BlacklistGuard HTTP API is authenticated with an API key sent in the X-API-Key header. This page covers creating, scoping, rotating, and securing your keys.

API keys

An API key is a secret credential tied to your workspace. Each key has a name and an optional expiry date, and gives access to your workspace's data, so treat it like a password. The secret is shown only once, when the key is created.

The console (cookie session) and the HTTP API (API key) are separate authentication paths for the same backend. Use API keys for server-to-server integrations; use the console for interactive administration.

Create a key

In the console, open API keys (under Infrastructure). Creating and changing keys needs a workspace admin; other members can see the list but not edit it.
Click New key and give it a descriptive name (e.g. orders-service-prod).
Optionally set an expiry date.
Copy the key now. It won't be shown again. Store it in a secrets manager.

⚠If you lose a key you can't recover it. Create a new one and deactivate the old. Never commit keys to source control or ship them in client-side code.

Authenticate a request

Send the key in the X-API-Key header. The API base URL is https://app.blacklistguard.com/api/v1.

curl https://app.blacklistguard.com/api/v1/emails/send \
  -H "X-API-Key: efk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "customer@example.com", "subject": "Hi", "body": "<p>Hello</p>" }'

ℹAuthentication uses the X-API-Key header, not an Authorization: Bearer header. Requests with a missing or invalid key are rejected.

Responses & errors

All JSON endpoints return a standard envelope. On success:

{ "success": true, "data": { /* ... */ }, "message": "..." }

On failure, including an authentication failure:

{ "success": false, "error": "Invalid or missing API key", "code": "..." }

An invalid or missing key returns HTTP 401. A key that lacks the required permission returns 403 with the code INSUFFICIENT_SCOPE. See Permissions.

Permissions

Every API key carries a list of permissions, each written as resource:action, for example campaigns:send. A key may also hold a wildcard: campaigns:* for every action on one resource, *:read for read access everywhere, or *:* for full access. Permissions are chosen when you create the key and can be changed later.

The full list of resources and actions is served by the API itself, so it never goes out of date:

GET /api-keys/permissions

It returns every resource with its label, group, available actions and the exact permission string to use, plus the wildcards and ready-made presets. Always take permission strings from this endpoint rather than composing them by hand.

Which permission an endpoint needs

GET and HEAD require the read action; POST, PUT, PATCH and DELETE require write.
Action endpoints require their own action instead: POST /campaigns/{id}/send needs campaigns:send, POST /autoresponders/{id}/trigger needs autoresponders:trigger, and the subscriber and suppression import endpoints need …:import.
Nested endpoints resolve to the resource being acted on, not the first path segment. POST /mailing-lists/{id}/subscribers needs subscribers:write, not mailing-lists:write.
A few account endpoints (/auth/*, /admin/users, /admin/current-session, /admin/clear-plan-intent) are intended for signed-in sessions rather than API keys. A key can only reach them with *:*.

When a permission is missing

The request is refused with HTTP 403 before it does anything:

{
  "success": false,
  "error": "This API key is missing the required permission.",
  "code": "INSUFFICIENT_SCOPE",
  "required_scopes": ["campaigns:send"]
}

required_scopes is always an array, and it lists what this key is missing, not everything the endpoint needs. Add those permissions to the key, or use one that already has them. Every value it contains is a real permission from /api-keys/permissions, so you can look it up there to show a readable name.

Manage & rotate keys

From the API keys screen you can see each key's name, permissions, last-used time, expiry, and status. You can:

Deactivate a key to revoke it immediately, and reactivate it later if needed.
Edit a key's name, permissions, or expiry.

To rotate without downtime: create a new key, deploy it to your service, confirm traffic is flowing on the new key (check last used), then deactivate the old one.

Security best practices

Call the API from your server, never the browser or a mobile app.
Use a separate key per integration so you can revoke one without affecting others.
Remember a key has access to your workspace's data, so limit who can see it and where it's used.
Store keys in a secrets manager, not in code or env files committed to git.
Rotate periodically and whenever a key may have been exposed.