---
title: "Mint an API key (first-party, JWT-authenticated)"
method: POST
path: "/api/v1/keys"
tags: ["API Keys"]
---

# Mint an API key (first-party, JWT-authenticated)

`POST /api/v1/keys`

## Request

- Base URL: `https://api.reconcileiq.com`
- URL: `https://api.reconcileiq.com/api/v1/keys`
- Auth: HTTP bearer

Creates a new API key for the logged-in web user. The plaintext key is returned exactly once and is never recoverable afterwards. This endpoint is authenticated by the first-party web session (JWT bearer token), NOT by an API key. On authentication failure it returns the standard error envelope (`401 unauthorized` if the token is missing, `401 invalid_token` if it is invalid or expired), with a `request_id`.

## Request body

- object
  - `name` string, required
  - `scopes` Scope[], required: Unique list of scopes. Duplicates are rejected.
  - `allow_overage` boolean: When true, this key is permitted to incur overage charges (still also requires the request and the subscription to allow overage).
  - `organisation_ids` integer[]: Restrict this key to these IQ Books organisations. Omit for every organisation you belong to. Naming one is how a practice gives an agent a single client: the key cannot see or touch any other set of books. Organisations you are not a member of are refused with 422.

## Response `201`

Key created. `key` is shown only here.

- object
  - `id` integer, required
  - `name` string, required
  - `prefix` string, required: 12-char lookup handle (also the middle segment of the key).
  - `scopes` Scope[], required
  - `allow_overage` boolean, required
  - `key` string, required: Full plaintext key, format iqk_<prefix>_<secret>. Shown ONCE.

## Other responses

- `400`: Structurally invalid request (Zod). Distinct from the 422 format-contract gate.
- `401`: First-party web-session (JWT) auth failure on a /api/v1/keys endpoint. Standard error envelope, identical in shape to API-key auth failures: `401 unauthorized` when the token is missing, `401 invalid_token` when it is invalid or expired.

---

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