# Create API key

> POST /api-keys — dashboard-only. Keys are generated in the dashboard; an API key cannot mint a key.

`POST /api-keys`

> **Warning:** **Dashboard-only.** API keys are generated on the website. A request authenticated with an API key is refused with `403 dashboard_only` — "API keys can only be created, edited and revoked from the SendPing dashboard, not with an API key." — no matter what permission that key holds. Create keys from the dashboard under **API Keys**.

> **Note:** This is a **breaking change**. Automation that used to mint keys with a `full_access` key now receives `403 dashboard_only` and must be replaced by a person creating the key in the dashboard and storing it in your secret manager. The official SDKs deliberately expose no method for this endpoint.

Creates a new API key and returns the full `mb_...` token **once**. Only the hash and prefix are stored, so copy the token immediately. The reference below describes the request the dashboard makes on your behalf with a signed-in session — it is not callable with an API key.

**Body parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | A label for the key. Maximum 50 characters. |
| `permission` | full_access | sending_access | No | The access level. `full_access` (default) can create, delete, get, and update any resource; `sending_access` can only send emails. |
| `domain_ids` | string[] | No | Restrict the key to send only from these domains — enforced on every send surface (`POST /emails`, batch, campaign sends, and receiving reply/forward). Only valid with `sending_access` — full-access keys always work across all your domains. Omit (or send an empty array) to allow all domains. |
| `domain_id` | string | No | Legacy single-domain form of `domain_ids`. Provide one or the other, not both. |

### Response

For the dashboard session, the created key is returned with its one-time `token`:

```json
{
  "id": "1042",
  "object": "api_key",
  "token": "mb_AbC123dEf456GhI789jKl012mNoPqRs",
  "domain_id": null,
  "domain_ids": null
}
```

### Response to an API-key caller

```json
{
  "statusCode": 403,
  "name": "dashboard_only",
  "message": "API keys can only be created, edited and revoked from the SendPing dashboard, not with an API key."
}
```

> **Warning:** The `token` is shown exactly once. Errors: `dashboard_only` (403) for **every** API-key caller — this check runs before any validation; `missing_required_field` if `name` is absent; `validation_error` if `permission` is not `full_access` or `sending_access`, if both `domain_id` and `domain_ids` are provided, if a domain restriction is combined with `full_access`, if `domain_ids` references a domain that is not yours, or if `domain_ids` contains more than 50 domains. Two 429s guard key sprawl: `rate_limit_exceeded` — "Max 5 keys per hour. Try again later." — once you have created 5 keys in the last hour, and `max_active_keys` — "Max 20 active keys. Revoke unused keys first." — once 20 unrevoked keys already exist on the account.