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

# Mint a key

`POST /api/keys`

## Request

- Base URL: `https://morfee.furo.solutions`
- URL: `https://morfee.furo.solutions/api/keys`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

The `key` field of the answer is the only time the secret is readable, here or anywhere: what is stored is a hash. Store it in the same step that makes it, because a caller that does not has no way back to it and has to make another one.

A key can only make one as narrow as itself, so a `render` key asking for `full` is a 403 rather than a quietly narrowed key. Give every system its own, then revoking one upsets nothing else.

Needs a key scoped `write` or `full`.

## Request body

- NewKey: What POST /api/keys takes. A name is required: a key you cannot tell apart from the others is a key you cannot revoke with any confidence.
  - `name` string, required: What this key is for.
  - `scope` 'read' | 'render' | 'write' | 'full': Never wider than the key asking. A `render` key cannot mint a `full` one, otherwise a narrow key would be a full key with one extra call in front of it.
  - `expiresInDays` integer: Or `expiresAt`. Leave both out for a key that does not expire.
  - `expiresAt` string, date-time: An absolute moment. In the past is a 400: the key would be dead on arrival.

## Response `200`

The key, once.

- object
  - `ok` boolean
  - `key` string: The secret. This is the only answer it ever appears in.
  - `id` string
  - `prefix` string
  - `scope` 'read' | 'render' | 'write' | 'full'
  - `expiresAt` string, date-time, nullable
  - `hint` string

## Other responses

- `400`: No name, a scope that does not exist, an expiry that is not a date, or one that has already passed. The message says which, and the hint shows a body that would work.
- `401`: No key, an unknown key or a revoked one.
- `403`: Two things land here. A key too narrow to make keys at all, and a key wide enough to make keys asking for a scope wider than its own.

---

[API](https://skmtc.dev/furo/apis/morfee.md) · [All operations](https://skmtc.dev/furo/apis/morfee/llms.txt) · [OpenAPI document](https://skmtc.dev/furo/apis/morfee/revisions/83f95f89653f?raw)