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

1. In the console, open API keys (under Infrastructure).
2. Click New key and give it a descriptive name (e.g. orders-service-prod).
3. Optionally set an expiry date.
4. Copy the key now — it won't be shown again. Store it in a secrets manager.

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>" }'

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.

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 — 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.