API Keys

Scoped management keys for CI pipelines, agents, and integrations — long-lived credentials with server-enforced permission ceilings.

Keys vs. SDK keys

Your environment's pk_live_... key is a public SDK key — it ships inside your app and identifies your project to the data plane. Management API keys (kb_live_...) are secret credentials for the management plane: creating collections, editing rules, deploying functions, publishing code-push bundles.

Never ship a kb_ key

A kb_ key is a secret. Never embed one in client code, a mobile app, or a public repository. Client apps use the environment's pk_live key only.

Scopes

Every key carries one scope. Scopes are ceilings, enforced by the API server on every request — a leaked key can never do more than its scope permits, regardless of what client wields it.

readConfiguration and operational visibility — projects, schema, records, flags, configs, analytics, patch history.

writeEverything in read, plus mutations — schema changes, record writes, flag and config updates, function deploys, bundle uploads. Also two reads that are not configuration: snapshot export, which embeds your function source, and end-user data — user lists, account locks, and the authentication audit trail.

adminEverything in write, plus operations that destroy or affect production: pruning collections during a snapshot apply, publishing or recalling code-push bundles, and disabling, enabling, or deleting end users (disable revokes live sessions immediately).

Scope follows exposure, not HTTP method

Most reads are read-tier, but a few are not, and the method is not what decides it. What matters is what the response exposes and what the operation destroys.

A snapshot export is a GET, but it embeds the source of every function in the project — that is your backend logic, not configuration, so it requires write. The same applies to your end users' data: a key that lists a project's users, their lockout state, or their sign-in history is reading personal information about people who are not your customers' developers.

read is the credential you hand a monitoring job or a status page. It should never be able to export your code or your users.

A request beyond a key's scope returns 403 with code insufficient_scope and a message naming the required scope. Start agents and CI on read; grant higher scopes deliberately.

Endpoints

POST/v1/organizations/{org_id}/api-keysMint a key (dashboard session only)

GET/v1/organizations/{org_id}/api-keysList keys (prefix, scope, last used)

DELETE/v1/organizations/{org_id}/api-keys/{key_id}Revoke — effective immediately

Creating a key

Keys are minted from a dashboard session — API keys cannot create other keys. The secret is returned once; store it immediately. Only the prefix is shown afterwards.

// POST /v1/organizations/{org_id}/api-keys
// Authorization: Bearer <dashboard session>
{ "name": "ci-deploy", "scope": "write" }

// Response 201
{
  "key": {
    "id": "7071409b-...",
    "key_prefix": "kb_live_4f2a",
    "scope": "write",
    "created_at": "2026-07-10T23:08:09Z"
  },
  "secret": "kb_live_4f2a..."   // shown once — store it now
}

Using a key

Send it as a Bearer token on management endpoints:

curl https://api.koolbase.com/v1/organizations/{org_id}/projects \
  -H "Authorization: Bearer kb_live_..."

CLI and CI

The Koolbase CLI accepts a kb_ key as its api_key config value — preferable to a dashboard session token for CI, since keys don't expire with your login session and carry a bounded scope.