---
title: "Create pod API key"
method: POST
path: "/v1/pods/{id}/api-keys"
tags: ["pods"]
---

# Create pod API key

`POST /v1/pods/{id}/api-keys`

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/pods/{id}/api-keys`
- Auth: HTTP bearer

Mint an API key scoped to this pod. The key can read and send from the pod's inboxes, create and delete inboxes in this pod, mint/revoke inbox keys for those inboxes, and manage pod/inbox policy and pod-scoped domains. It cannot change webhook config, manage pods, mint further pod keys, reach another pod, or address account-wide policy or domains. The full `token` is returned once, here — store it securely, it cannot be retrieved again. Requires an account-wide key (a pod-scoped key cannot mint keys).

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string, nullable: Human-readable label to identify the key later.

## Response `201`

API key created

- ApiKeyWithToken
  - `id` string: OpenMail API key ID
  - `name` string, nullable: Human-readable label for the key, if set.
  - `podId` string, nullable: ID of the pod this key is scoped to, or null for an account-wide key. A pod-scoped key can only access resources in this pod.
  - `inboxId` string, nullable: ID of the inbox this key is confined to, or null. When set, the key can only access this single inbox and its threads, messages, and drafts (its `podId` is the inbox's pod).
  - `tokenPrefix` string: Non-secret leading characters of the token, to help you identify it.
  - `last4` string: Last 4 characters of the token, shown alongside the prefix.
  - `createdAt` string, date-time
  - `lastUsedAt` string, date-time, nullable: When the key last authenticated a request, or null if never used.

## Other responses

- `403`: The authenticating key is pod-scoped and cannot mint keys
- `404`: Pod not found
- `422`: The pod already has the maximum number of active keys (`api_key_limit_reached`)

---

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