---
title: "Mint a new API key"
method: POST
path: "/api/v1/keys"
tags: ["Keys"]
---

# Mint a new API key

`POST /api/v1/keys`

## Request

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

Create a new API key for this account. The requested scopes must be a subset of the calling key's scopes (a key can never widen authority). Requires the `keys:manage` scope. The secret is returned exactly once.

## Request body

- NewApiKeyRequest
  - `name` string, required: A human-readable label so you can tell keys apart (e.g. the agent or script that will use it). 1–80 characters.
  - `scopes` Scope[], required: The scopes to grant. MUST be a subset of the calling key's own scopes — a key can only ever mint a narrower-or-equal key, never a broader one. Duplicates are ignored.

## Response `201`

The key was created; the secret is in `api_key` (shown once).

- CreatedApiKey
  - `id` integer, required: The new key's id (use it to revoke).
  - `name` string, required: The label you supplied.
  - `key_prefix` string, required: Non-secret display prefix (`vrk_` + 4 hex). Safe to log/show.
  - `scopes` Scope[], required: The granted scopes, de-duplicated and in canonical order.
  - `created_at` integer, required: Epoch milliseconds (UTC).
  - `api_key` string, required: The full secret — SHOWN ONCE, right here. Store it now; it is never retrievable again. Send it on subsequent calls as `Authorization: Bearer <api_key>`.

## Other responses

- `400`: The request failed schema validation (`validation_error`). On the import endpoints, also when the text is UTF-16 (Excel "Unicode Text"; `unsupported_encoding`): resend it as CSV UTF-8.
- `401`: Missing or invalid API key.
- `403`: The API key lacks a scope required by this endpoint.
- `429`: Key issuance is being rate-limited for this account. Retry shortly.

---

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