---
title: "POST /api/v1/{context_id}/keys"
method: POST
path: "/api/v1/{context_id}/keys"
---

# POST /api/v1/{context_id}/keys

`POST /api/v1/{context_id}/keys`

Mint a new data-plane API key bound to the caller's own principal. The optional `grants` body only attenuates (never widens) the caller's effective grants. Gated by the Context's `allow_self_service_keys` flag; rejects legacy / delegated callers.

## Path parameters

- `context_id` string, required

## Query parameters

- `ttlSeconds` integer, nullable

## Request body

- MintKeyBody — Request body for `POST /{ctx}/keys`. Every field is optional — an empty body mints a key inheriting the caller's grants with no expiry, named after the random key id.
  - `grants` object, nullable — Optional attenuating per-verb grant map. Every requested pattern must be ⊆ the caller's effective region for that verb (fail-closed); an out-of-range pattern returns 400. Absent ⇒ inherit principal grants.
  - `name` string, nullable — Optional human-readable name (unique per Context). Auto-derived from the minted key id when absent.

## Response `201`

Plaintext key returned once

- MintedKeyJson — `POST /{ctx}/keys` response. The plaintext key is returned **once** and never persisted in this shape — the caller must store it themselves.
  - `id` string, required — The key's stable record-id key (survives rotation).
  - `key` string, required — The full bearer key (`sp-{id}-{secret}`). Send as `Authorization: Bearer …`.
  - `validUntil` string, date-time, nullable — Mint-time expiry. Absent ⇒ no expiry.

## Other responses

- `400` — Invalid grants or attenuation widens
- `401` — Unauthorized
- `403` — Self-service keys disabled or ineligible caller
- `409` — Key name already taken in the Context
- `422` — Invalid context id

---

[API](https://skmtc.net/surrealdb/apis/spectron.md) · [All operations](https://skmtc.net/surrealdb/apis/spectron/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/surrealdb/spectron/revisions/52b41ab517b6/schema)