---
title: "POST /v1/mailbox-keys"
method: POST
path: "/v1/mailbox-keys"
---

# POST /v1/mailbox-keys

`POST /v1/mailbox-keys`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-better-auth.session_token`

Rotate a mailbox's API key. The new key is answered once; the old one stops working now.

## Request body

- MailboxKeyRotate
  - `mailboxId` string, required: The org's mailbox id — `Mailbox.id`, not the engine account.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- MailboxKeyRotated: Carries the mailbox's `bk_` key **once**. Only its hash is stored, on the engine, so nothing — including this API — can produce it again. The previous key stops authenticating the moment this answers: there is no grace period, because a leaked key that keeps working is not revoked.
  - `id` string, required
  - `label` string, required
  - `engineAccountId` string, nullable, required: The engine account this container lives on. What keeps a caller's correlation wire-level: token props name mailboxes by engine id, and this is that id. Null while `provisioning`, and on a `failed` claim.
  - `keyPrefix` string, nullable, required: The displayable head of this mailbox's engine key. The key itself is minted on the engine and is not held here.
  - `status` 'provisioning' | 'active' | 'failed', required
  - `createdAt` string, date-time, required
  - `apiKey` string, required: The API key — the bearer the mailbox surface takes. Shown once and never again.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/foundermail/apis/org.md) - [All operations](https://skmtc.dev/foundermail/apis/org/llms.txt) - [OpenAPI document](https://skmtc.dev/foundermail/apis/org/revisions/8bbb36e378ab?raw)