API Keys
Organization API keys authenticate programmatic access to Koolbase — the CLI, the MCP server, CI pipelines, and scripts. Every key carries a scope that is the hard ceiling on what it can do.
Scopes
readInspect configuration — collections, buckets, functions, flags, usage. Cannot change anything, and cannot read your function source or your end users' data.writeEverything read can do, plus create and update. Also snapshot export and end-user data — user lists, account locks, authentication audit.adminEverything write can do, plus operations that destroy: pruning collections during a snapshot apply, publishing code-push patches, deleting end users.Scopes are enforced server-side on every request. Give each integration the least scope it needs — a dashboard-reading assistant needs read; reserve write and admin for keys that are meant to change things.
A scope is not decided by whether a request reads or writes, but by what the response exposes and what the operation destroys — which is why a few reads sit above read. See the API reference for the full rule.
Creating keys
Dashboard: Settings → API Keys → Create. Name the key after what will use it (e.g. claude-desktop, ci-deploy), pick a scope, and copy the secret immediately — it is shown exactly once and cannot be retrieved again.
CLI: after koolbase login:
koolbase keys create --name my-key --scope readCreating a key always requires a logged-in session — API keys cannot mint other keys, so a leaked key can never escalate or multiply itself.
Managing keys
List keys (with prefix, scope, and last-used time) and revoke them from the dashboard or the CLI:
koolbase keys list
koolbase keys revoke <key_id>Revocation takes effect immediately — anything authenticating with the key stops working on its next request. Prefer one key per machine or integration so revocation is surgical rather than disruptive.
Attribution
Every resource created through the API records who created it. Resources created by a logged-in user carry created_by (the user’s id); resources created with an API key carry created_by_key_id (the key’s id, visible in koolbase keys list). Exactly one of the two is set, and each is omitted from responses when empty.
Why it matters: named keys make audit trails readable. A release created by ci-deploy is distinguishable from one a teammate cut by hand — one more reason to mint one key per integration instead of sharing a key across machines.
Isolation
A key belongs to exactly one organization and can only see and act on that organization’s resources. Requests for resources in any other organization return 404 not-found — not 403 forbidden.
Why not-found instead of forbidden? A 403 confirms the resource exists; a 404 reveals nothing. Koolbase never confirms the existence of resources to a caller who cannot access them. If you are debugging a 404 you did not expect, the first thing to check is that the key and the resource belong to the same organization.