Built with Chinaski

API Keys

API keys authenticate machine access — scripts, cron jobs, and the built-in MCP server — to Chinaski’s REST API. Access lives under Settings → API Keys (/admin/api-keys), admin-only. This page covers creating, scoping, and revoking them; the request model (scopes, rate limits) is on its own Automation page.

Creating a key

  • Click create; give the key a name (required; names are the forever audit identifiers) and a permission:
    • read — can fetch content but never modify.
    • write — can create and update; required for every mutating call.
  • Optionally set an expiry date (a plain date; leaving it empty means the key never expires).
  • The key itself is a long random string generated by a secure random source — shown exactly once on a copy field right after creation, with an explicit note that it will not be shown again. Only a hash of it is stored (and for newly created keys, a bcrypt verification layer on top), so a leaked database cannot reveal live keys.
  • Creations are audited (the action names the key and its scope).

Scoping in practice

  • Cards flux-group read/write by design: read scope can’t create or edit anything.
  • Write scope required for every content-manipulating endpoint, both for “safe” and administrative paths — so a key minted as a read-only reporter can’t sneak past the gate by striking a lesser-known route.
  • A wide assertion gate in front of session-authenticated routes now checks scope per method, so write calls with read keys get a clean 403 rather than silent permission bleed.

Rate limiting

Rate limiting is per key, per rolling 60-second window, defaulting to 100 requests per minute (configurable in Settings → Security: “API key rate limit”). Crossing the limit returns a 429 response with a Retry-After header telling the script how long to wait. Each request bumps the counter exactly once, regardless of how many internal auth layers it passes through.

Key use feedback: each key records the last time it authenticated; recent usage is visible on the keys screen, and each request is audited (method and path), which is the fastest way to find abandoned keys.

The kill switch

The master “API access” toggle on the same screen disables all API requests, in a single switch. With access off, the API answers every request with a 503, ignoring keys — useful during incidents without hunting your key list. The toggle action itself is audited with the resulting state.

Revoking

Deleting a key is instant and audited: the key stops working immediately afterward. The safest clean-up habit: audit trail finds last-used dates per key; a key with a stale last-used timestamp and a test-run origin makes for a tidy retirement policy.