# How to handle API keys securely

> Best practices for MailBlastr API keys: keep them server-side, scope them to sending, rotate them, and revoke leaked keys.

A MailBlastr API key (it starts with `mb_`) authenticates every request as your account. Treat it like a password: anyone who has it can send email as you and, for a full-access key, manage your domains and other keys. The full key is **shown only once** at creation and is stored only as a **hash** afterward — MailBlastr can never show it to you again.

## Keep keys server-side only

- Call the API **from your server**, never from a browser, mobile app, or any other client the user controls — see [How do I fix CORS issues?](https://www.mailblastr.com/docs/kb/cors).
- Never commit keys to source control, embed them in client-side code, or paste them into logs, screenshots, or support tickets.
- Store keys in a **secret manager** or environment variable, not in your codebase.

> **Warning:** If a key ever appears in client-side code, a public repo, or a shared log, treat it as compromised and revoke it immediately.

## Use the least-privileged scope

API keys carry a permission level. Pick the **narrowest** one that does the job:

| Permission | Can do | Use for |
| --- | --- | --- |
| **sending_access** | Send email only. | Any server that only needs to send transactional or marketing email. |
| **full_access** | Send email **and** manage domains, audiences, contacts, campaigns, and API keys. | Administrative tooling that genuinely manages resources. |

A `sending_access` key is the safe default: even if it leaks, it cannot delete your domains or mint new keys. See [Authentication](https://www.mailblastr.com/docs/authentication) and [Create API key](https://www.mailblastr.com/docs/api/api-keys-create).

## Rotate and revoke

MailBlastr API keys **do not expire automatically** — a key stays valid until you revoke it, with no built-in expiry or auto-rotation. Rotating them yourself on a schedule is what keeps a forgotten or leaked key from being a long-lived liability. Rotate **at least every 90 days**, and immediately if you suspect a key is compromised.

- **Rotate periodically.** Create a new key, deploy it, then revoke the old one — keys are cheap, so rotate on a schedule and whenever someone with access leaves.
- **Revoke leaked keys immediately.** Revoking a key takes effect right away; subsequent requests with it return `403 invalid_api_key`.
- **Use separate keys per service** so you can revoke one without disrupting the others.
- **Delete stale keys.** If a key has not been used recently, delete it rather than leaving it active — an unused key is just attack surface. Keys idle for 30+ days are flagged in the dashboard to help you find them.

### How to rotate without downtime

Both the old and new key work at the same time, so rotate by overlapping them — never delete the old key first:

1. **Create a new key** — Mint a replacement with the **same permission level** as the key you are retiring, in the dashboard or via [Create API key](https://www.mailblastr.com/docs/api/api-keys-create).
2. **Update every service** — Deploy the new key to all environments that reference the old one.
3. **Verify it is working** — Confirm the new key is in use — for example by filtering the [logs](https://www.mailblastr.com/docs/logs/overview) by API key and checking for recent requests — before going further.
4. **Revoke the old key** — Only once the new key is confirmed live everywhere, delete the old key. You can script the whole flow with the create, list, and delete API-key endpoints.

> **Warning:** Do not delete the old key before the new one is deployed everywhere. Because both keys work simultaneously, verifying the new key first means zero downtime during the transition.

> **Note:** Manage keys in the dashboard under **API Keys**, or via the [API](https://www.mailblastr.com/docs/api/api-keys-create). Because the full key is shown only once, store it safely at creation time — if you lose it, revoke and create a new one.