---
title: "Mint Key"
method: POST
path: "/v1/keys"
tags: ["keys"]
---

# Mint Key

`POST /v1/keys`

## Request

- Base URL: `https://api.craterview.ai`
- URL: `https://api.craterview.ai/v1/keys`
- Auth: HTTP bearer

Create another key on your account.

**The value is in this response and nowhere else.** Keys are stored as hashes, so a key
that is not written down is a key that has to be replaced rather than recovered.

Every key on an account shares that account's credits, job history and job ceilings, and
carries its own request rate limit. Several is the ordinary arrangement: one per service
or per environment, so that revoking one does not stop the others.

This is also how you rotate without downtime — create the new key, move your clients onto
it, then revoke the old one. There is no window in which nothing works, which is why
there is no single "rotate" call.

**An account is given a limited number of new keys in any hour**, whichever of its keys
asks; past it this is refused with 429 and `Retry-After`. Revoking is never limited. Each
request also counts against the calling key's own request rate, as a submission does.

## Request body

- MintRequest
  - `name` string: A label to tell this key from your others in a listing. Not a secret and not interpreted.

## Response `201`

Successful Response

- NewKey: A freshly minted key. The only response that contains a usable value.
  - `id` string, required: Identifies this key, for revoking it.
  - `key` string, required: The key itself. This is the only time it is returned — it is stored as a hash, so it cannot be shown again and cannot be recovered for you.
  - `prefix` string, required: The opening characters of the key, for telling your keys apart once the secret is no longer shown.
  - `name` string, required: The label you gave this key.
  - `rate_limit_per_minute` integer, required: Requests a minute this key may make before it is throttled.

## Other responses

- `400`: the path, query or a JSON string in the body contains a NUL character or an unpaired surrogate; the body is not JSON encoded as UTF-8, or carries a number JSON cannot represent (NaN, Infinity, or one too large) or nesting too deep to read; or an Idempotency-Key header is longer than 255 characters or not printable ASCII. The request was not read
- `401`: missing, malformed or unrecognised API key
- `404`: the key you are calling with no longer reaches an account
- `413`: the request body is larger than 1 MiB. The request was not read
- `422`: Validation Error
- `429`: the calling key's request rate is exceeded, or the account has been given as many new keys this hour as it may
- `502`: the request could not be applied; ask again
- `503`: key management is briefly unavailable; retry the request

---

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