API Keys

Create, list, rename, and revoke the API keys for your tenant. All routes are Bearer-authenticated; the tenant is derived from your key.

Endpoints#

Method	Path	Purpose
`GET`	`/v1/keys`	List keys (prefixes + metadata only; never the secret).
`POST`	`/v1/keys`	Mint a new key; secret returned once in `apiKey`.
`PATCH`	`/v1/keys/:prefix`	Set or clear a key's `label`.
`DELETE`	`/v1/keys/:prefix`	Revoke a key (idempotent).

Create a key#

cURL

curl -X POST https://api.maddoxapi.dev/v1/keys \
  -H "Authorization: Bearer $MADDOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "ci-pipeline" }'

Response

{ "status": "ok", "apiKey": "…64 hex…", "key_prefix": "3c8f1a90", "label": "ci-pipeline" }

The new secret is returned once, in the apiKey field. An optional label (≤ 64 chars) helps you tell keys apart later.

Notable Behaviors#

Hard cap per plan — exceeding it returns 409 ApiKeyCapExceeded.
Self-revoke guard — revoking the key you authenticate with needs ?confirm=true, else 409 SelfRevokeRequiresConfirm. Prefer create-then-revoke rotation.
One-time secret — the full key is shown only at create time; afterwards only the 8-char prefix.

NoteThe conceptual model — one-time secret, rotation, the hard cap — is covered end-to-end in Authentication.

Authentication

The full key lifecycle, in plain English.

Plans & Quotas

The per-plan API-key cap.