Keys API (/keys)

Routes for issuing and revoking API keys created through the HTTP API. Issued keys work alongside keys your operator configures on the deployment.

All paths are prefixed with /keys.

---

Quick reference

Method	Path	Master key only
POST	/keys	Yes
GET	/keys	Yes
DELETE	/keys/:id	Yes

Minter and read keys can call factory and certificate routes per HTTP API overview; they receive 403 on every /keys route.

---

POST /keys

Purpose

Creates a new issued API key with role minter or read and returns the secret once in the response body. Use this to onboard integrators without asking the operator to rotate bootstrap keys.

Auth

When API key auth is enabled:

• Send x-api-key with a master key.
• 401 — missing/invalid key.
• 403 — non-master key (minter/read).

Request

• Headers: Content-Type: application/json
• Body (JSON):

Field	Type	Required	Notes
role	string	Yes	Must be "minter" or "read".
label	string	No	Human-readable label for operators.

Semantics

• The plaintext key is only returned in the 201 response (key field). Store it securely; it is not shown again.
• createdAt is an ISO 8601 string from the server (e.g. new Date().toISOString()).

Responses

201 Created — JSON body:

Field	Type	Notes
id	string	Stable id for DELETE /keys/:id.
key	string	Secret value for x-api-key.
role	string	"minter" or "read".
label	string	Present only if provided.
createdAt	string	Issue time.

Errors

Status	Typical message or body
400	Invalid JSON body, Expected JSON object, role must be "minter" or "read", label must be a string
401	Missing x-api-key header, Invalid API key
403	Only a master API key can access key management
500 / 502	Storage or internal error (shape: { "message" })

Example

BASE_URL="https://ebg-tokenizer.u3dev.deno.net"
curl -sS -X POST "$BASE_URL/keys" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MASTER_KEY" \
  -d '{"role":"minter","label":"Partner mint CI"}'

---

GET /keys

Purpose

Lists issued keys (id, role, optional label, createdAt). Never returns secret key material.

Auth

Same as POST /keys: master x-api-key only (401 / 403 otherwise).

Request

No body. No path parameters.

Responses

200 OK:

{
  "keys": [
    {
      "id": "…",
      "role": "minter",
      "label": "Partner mint CI",
      "createdAt": "…"
    }
  ]
}

(Exact list shape matches the server; entries omit secret material.)

Errors

Same 401 / 403 / 500 / 502 patterns as POST /keys.

Example

BASE_URL="https://ebg-tokenizer.u3dev.deno.net"
curl -sS "$BASE_URL/keys" -H "x-api-key: $MASTER_KEY"

---

DELETE /keys/:id

Purpose

Revokes an issued key by id (from POST /keys or GET /keys). Bootstrap keys from the operator are not revoked through this API.

Auth

Master x-api-key only (401 / 403 otherwise).

Request

Param	Notes
:id	Issued key id string.

No body.

Responses

204 No Content — empty body on success.

Errors

Status	Typical message
400	Missing key id
404	API key not found
401 / 403	Same as other /keys routes

Example

BASE_URL="https://ebg-tokenizer.u3dev.deno.net"
curl -sS -X DELETE "$BASE_URL/keys/$KEY_ID" -H "x-api-key: $MASTER_KEY" -i

---

Errors (shared)

Validation issues use { "message": string }. See HTTP API overview — Conventions.

When API key checks are disabled, /keys may still be reachable—treat access as a deployment concern and restrict at the network layer if needed.