---
title: "Issue a new API key"
method: POST
path: "/v1/accounts/{id}/api-keys"
tags: ["Accounts"]
---

# Issue a new API key

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

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/accounts/{id}/api-keys`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Requires `api_keys:w`.

## Path parameters

- `id` string, required

## Headers

- `x-step-up-token` string

## Request body

- object
  - `mode` 'live' | 'test': Defaults to the calling key's mode. A test key can only create test keys.
  - `label` string
  - `permissions` object: Per-resource permissions. Each key is a resource name; value is a string of allowed operations: r=read, w=write, m=modify, d=delete. Omit a resource to deny all access to it. Example: { "messages": "rw", "contacts": "r" }. When omitted, the new key gets the calling key's permissions. A key can only grant permissions it holds itself, unless the request carries an `api_keys:elevate` step-up token (X-Step-Up-Token). A test key can only create test keys. A dashboard session key (the one login mints) always needs that step-up to create a key, even one no broader than itself.
  - `email_domain_ids` string[]: Restrict the key to sending email from these domains (ids from /v1/email-domains). Omitted: the key inherits the calling key's restriction, if any. A restricted key can only create keys restricted to a subset of its own domains, unless the request carries an api_keys:elevate step-up token.

## Response `201`

API key issued. The raw key is shown only once: store it securely.

- object: API key issued. The raw key is shown only once: store it securely.
  - `key` string: Full API key (shown once only)
  - `prefix` string: Non-secret prefix for display/identification
  - `mode` 'live' | 'test'
  - `permissions` Def0: Per-resource permissions.
  - `email_domain_ids` string[], nullable
  - `notice` string

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: FORBIDDEN (not your account), LIVE_KEY_REQUIRED (a test key asked for a live key), KEY_FENCED (the calling key has an allow/deny fence), or PERMISSION_ESCALATION (broader permissions or email domains than the calling key, or a dashboard session key, without an api_keys:elevate step-up).
- `422`: VALIDATION_ERROR: the request failed validation; details names the fields.
- `429`: Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).
- `500`: Unexpected server error.

---

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