# API keys

> Create, scope, edit, and revoke API keys in the dashboard. Keys start with mb_, carry a full_access or sending_access permission, and are shown in full exactly once.

Every API request authenticates with an API key sent as a Bearer token (see [Authentication](https://www.sendping.co/docs/authentication)). Keys are created, re-scoped and revoked **in the dashboard** under **API Keys** — see [Create an API key](https://www.sendping.co/docs/create-an-api-key).

A key is returned **once** at creation — the full `mb_...` token is shown a single time, and only its hash and prefix are stored afterward. If you lose it, create a new one.

> **Warning:** Copy the key immediately when you create it. SendPing cannot show it again; there is no way to recover the full token later.

## Permissions

Each key has a permission level that controls what it can do:

| Permission | Can do |
| --- | --- |
| `full_access` | Send email **and** manage resources — domains, audiences, contacts, campaigns, and webhooks. It can *list* API keys, but cannot create, re-scope or revoke them. |
| `sending_access` | Send email only. Cannot create or delete domains, audiences or campaigns. |

Prefer a `sending_access` key for any server that only needs to send email — it limits the blast radius if the key leaks.

> **Warning:** No API key can create, re-scope or revoke an API key — `POST /api-keys`, `PATCH /api-keys/:id` and `DELETE /api-keys/:id` answer `403 dashboard_only` to every key, whatever its permission. Key lifecycle is dashboard-only by design, so a leaked key can never mint itself a replacement or widen its own access.

You can create multiple keys to isolate different applications or environments. Scoping each integration to its own key lets you track its usage independently, spot abuse, and revoke just that key if it leaks — without disrupting your other services.

## Tracking usage

Each key records when it was **last used**. List your keys with [`GET /api-keys`](https://www.sendping.co/docs/api/api-keys-list) — each entry carries a `last_used_at` timestamp (null if the key has never been used) alongside its `name` and `created_at`. The dashboard surfaces the same signal so you can scan which keys are active and which are dormant.

## Editing, rotation, and revocation

A key's **name, permission, and domain restriction** can be changed in place with [`PATCH /api-keys/:id`](https://www.sendping.co/docs/api/api-keys-update) — no need to mint a new token just to narrow or widen what an existing key may do. The secret itself is immutable: keys do not expire on their own, and to rotate one you create a new key, deploy it, then delete the old one — deletion is immediate and irreversible. A revoked key returns `403 invalid_api_key` on its next use.

> **Note:** If a key has not been used in the last 30 days, consider deleting it to keep your account secure. Dormant keys widen your attack surface for no benefit.

- Create a key: [`POST /api-keys`](https://www.sendping.co/docs/api/api-keys-create).
- List keys (metadata only — never the token): [`GET /api-keys`](https://www.sendping.co/docs/api/api-keys-list).
- Update a key's name, permission, or domain restriction: [`PATCH /api-keys/:id`](https://www.sendping.co/docs/api/api-keys-update).
- Revoke a key: [`DELETE /api-keys/:id`](https://www.sendping.co/docs/api/api-keys-delete).