# Create a key

`POST /api/api-keys`  (operationId: `createApiKey`, group: API keys)

Mints a key. The plaintext is in the response and cannot be shown again. Only workspace admins can create keys: in the dashboard, or with a full-access key created by an admin. Scopes may include the :read variants, which make a key that can call GET endpoints and can never change anything.

Part of the full API, which is included in the Scale plan. Workspace admin: a dashboard session, or a full-access key created by an admin. A scoped key is refused with scope_denied.

**Request body** (JSON, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | yes | A name to recognise the key by. |
| `scopes` | array of string | no | all, or any of the scopes from GET /api/api-keys/scopes. Default: all. |
| `expires_in_days` | integer | no | Expire after this many days. Or use expires_at. Range 1..730. |
| `expires_at` | string (date-time) | no | A future expiry, within 730 days. |
| `rate_limit_per_min` | integer | no | Per-key requests per minute. Omit for the workspace default. Range 10..100000. |

Example:

```json
{
  "label": "Dashboard",
  "scopes": [
    "inbox:read",
    "team_management:read"
  ],
  "expires_in_days": 90,
  "rate_limit_per_min": 120
}
```

**Response 200**: OK (schema `ApiKeyCreated`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer |  |
| `label` | string |  |
| `key` | string | The plaintext key. Shown once and never again. |
| `last_4` | string |  |
| `scopes` | array of string |  |
| `read_only` | boolean |  |
| `expires_at` | string (date-time), nullable |  |
| `rate_limit_per_min` | integer, nullable |  |
| `created_at` | string (date-time) |  |
| `message` | string |  |

Example:

```json
{
  "id": 7,
  "label": "Dashboard",
  "key": "iwk_2vN0k1...x9Kq",
  "last_4": "x9Kq",
  "scopes": [
    "inbox:read",
    "team_management:read"
  ],
  "read_only": true,
  "expires_at": "2026-12-24T10:00:00.000Z",
  "rate_limit_per_min": 120,
  "created_at": "2026-09-25T10:00:00.000Z",
  "message": "Save this key now. It can’t be shown again."
}
```

**Errors specific to this call.** The common ones (401, 403, 429 and the rest) are in the [Errors guide](https://inboxwa.online/docs/api/guide/errors.md).

| Status | error | When |
| --- | --- | --- |
| 400 | `label_required` | No label. |
| 400 | `invalid_scopes` | No valid scope in the list. |
| 400 | `invalid_expiry` | Expiry outside 1 to 730 days. |
| 400 | `invalid_rate_limit` | Limit outside 10 to 100000. |
| 400 | `too_many_keys` | The workspace already has 20 active keys. |

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json