Admin: API keys

Create, list and revoke API keys. All admin routes require a key with the admin tier.

POST /v1/admin/keys

POST/v1/admin/keys

Create a new API key. The raw key is returned exactly once — only its hash is stored, so it cannot be retrieved afterwards.

Parameter	In	Type	Description
name*	body	string	Human label, 1–100 chars (e.g. "client-portal-prod").
tier	body	string	Rate-limit tier: admin \| internal \| standard \| free. Default standard.

Request / response

POST /v1/admin/keys
X-API-Key: gw_admin_…

{ "name": "Firm staff tool", "tier": "internal" }

→ 201
{
  "id": "…uuid…",
  "name": "Firm staff tool",
  "tier": "internal",
  "key_prefix": "gw_internal_4f9a",
  "api_key": "gw_internal_4f9a_…full secret, shown once…",
  "rate_limit_per_minute": 240,
  "rate_limit_per_day": 20000,
  "created_at": "2026-10-09T12:00:00Z"
}

GET /v1/admin/keys

GET/v1/admin/keys

List keys — prefixes only, raw keys are unrecoverable.

Parameter	In	Type	Description
include_revoked	query	boolean	Include revoked keys. Default false.
limit	query	integer	Page size, 1–500. Default 100.
offset	query	integer	Page offset. Default 0.

Response (abridged)

{
  "data": [
    {
      "id": "…uuid…",
      "name": "client-portal-prod",
      "tier": "standard",
      "key_prefix": "gw_standard_51c2",
      "is_active": true,
      "created_at": "2026-10-01T09:00:00Z",
      "revoked_at": null,
      "last_used_at": "2026-10-09T11:58:12Z"
    }
  ],
  "meta": { "total": 3, "limit": 100, "offset": 0 }
}

DELETE /v1/admin/keys/{key_id}

DELETE/v1/admin/keys/{key_id}

Revoke a key (soft delete — the audit trail is preserved). The key immediately returns 403. Revoking an already-revoked key returns 409 KEY_ALREADY_REVOKED.

Response

{ "data": { "id": "…", "is_active": false, "revoked_at": "2026-10-09T12:30:00Z", "…": "…" } }

Tiers

Tier	Per minute	Per day	Intended for
`admin`	500	50,000	Full access, including key management
`internal`	240	20,000	Firm staff tools
`standard`	60	10,000	Production client integrations
`free`	10	1,000	Evaluation / light use

Bootstrap admin key

The very first admin key can authenticate with the bootstrap key from the backend's ADMIN_API_KEY setting — no manual SQL needed.