---
title: "Create an API key"
method: POST
path: "/v1/keys"
tags: ["keys"]
---

# Create an API key

`POST /v1/keys`

## Request

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

Mints a new key. The full secret is revealed once, in this response only — only its argon2id hash is stored.

## Request body

- CreateKeyRequest
  - `label` string: Display label; blank is treated as no label.

## Response `201`

The new key — save `key` now; it cannot be retrieved again.

- ApiKeyCreated
  - `id` string, uuid, required
  - `key` string, required: The full bearer token (`mfx_…`) — shown exactly once.
  - `prefix` string, required: 8-char lookup prefix.

## Other responses

- `401`: Missing bearer token, malformed key, or unknown/revoked/invalid API key.
- `429`: Per-key rate limit exceeded. `Retry-After` says when the next request will be admitted; the RateLimit headers name the bucket that refused (`requests` or `creates`) with `r=0`.
- `500`: Unexpected server error. `detail` is null — internals are never leaked.

---

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