---
title: "Create an API key"
method: POST
path: "/v1/keys"
tags: ["keys"]
---

# Create an API key

`POST /v1/keys`

## Request

- Base URL: `https://botmail.pro`
- URL: `https://botmail.pro/v1/keys`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bm_session`

Scope: manage. Not for pending keys. A key can only create keys with
scopes it has, and a mailbox-restricted credential can only mint keys
for its own mailboxes. Max 100 active keys (409 too_many_keys).

## Request body

- object
  - `name` string
  - `scopes` Scope[]: Default `["read", "send"]`.
  - `mailbox_ids` string[]: Restrict to these mailboxes. Empty = every mailbox (or the caller's own restriction).

## Response `201`

Created. `secret` is shown only once.

- ApiKey
  - `id` string, required
  - `name` string, required
  - `kind` 'live' | 'pending', required
  - `prefix` string, required: First characters of the secret
  - `scopes` string[], required
  - `mailbox_ids` string[], required: Empty = every mailbox.
  - `created_at` string, date-time, required
  - `last_used_at` string, date-time, nullable, required
  - `last_used_ip` string, nullable, required
  - `secret` string: `bm_live_…`. Only in the create response.

## Other responses

- `400`: Invalid request (`bad_request` or a more specific code).
- `401`: Missing or invalid credentials (`unauthorized`, `invalid_token`).
- `403`: The credential can't do this (`forbidden`, `csrf`, `account_inactive`, …). Missing scopes are listed in `details.required_scope`; pending keys get a hint to wait for the claim.
- `409`: Conflicts with current state.

---

[API](https://skmtc.dev/botmail/apis/botmail-api.md) · [All operations](https://skmtc.dev/botmail/apis/botmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/botmail/apis/botmail-api/revisions/49f736362bf2?raw)