---
title: "Issue a new API key"
method: POST
path: "/v1/keys"
---

# Issue a new API key

`POST /v1/keys`

## Request

- Base URL: `https://api.reqbeat.com`
- URL: `https://api.reqbeat.com/v1/keys`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Self-serve key issuance: a developer who already holds one key can mint
another for their OWN account -- no operator step. `scopes` is the only
field the request body carries.

The new key's customer AND its tier are both taken from the AUTHENTICATED
caller's own key, never from the request, so a key can never be issued for
another tenant nor carry more entitlement than the key that authorized it.
Sending a `tier` is rejected with a 422 rather than ignored. To change your
tier, change your plan -- the new tier then applies to every key on the
account.

The mint also inherits the parent key's acquisition surface, exactly as
rotation carries it forward: an additional self-serve mint is the same
acquisition, and the same entitlement, as the key that authorized it.

`scopes`, omitted, inherits the presenting key's own scopes; sent
explicitly, it must be a subset of them -- a scoped-down key can never
mint itself a wider replacement. 403 names the excess when it isn't.

Requires the `account` scope.

## Request body

- IssueKeyRequest
  - `scopes` string[], nullable

## Response `201`

Successful Response

- IssueKeyResponse
  - `id` integer, required
  - `key` string, required
  - `customer_id` string, required
  - `account_id` integer, required
  - `tier` string, required
  - `scopes` string[], required

## Other responses

- `401`: No API key was sent.
- `403`: The presented key is invalid or revoked, or (see `x-required-scope` on this operation) it does not carry the scope this operation requires.
- `422`: Validation Error

---

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