API tokens & service accounts

An API token lets a program authenticate to Koo — the CLI, the SDKs, or direct calls to the REST API. Each token is a service account: a machine identity with a name and a role, confined to a single account.

Create a token

Open the account's Tokens page in the console and create a token with a name and a role. Koo shows the plaintext token — a bearer credential starting kc_… — once, at creation. Copy it then; afterwards the page shows only a masked prefix, and Koo cannot show the full value again. If you lose a token, revoke it and create a new one.

Roles

A token holds one role, chosen when you create it:

• Read — view-only access: dashboards, status checks, read-only integrations.
• Write — the right default for CI: it can deploy and manage services.

A token acts with exactly that role's permissions (see Teams & roles), and only within the account it was created in — it can never act in another account, and it can never manage members, plan, or billing.

Use a token

Send the token as a bearer credential on every request to the Koo API:

Authorization: Bearer kc_…

The CLI reads the same token from the KOO_TOKEN environment variable, so a single credential covers your terminal, your CI pipeline, and your own scripts. The Node SDK Coming soon, Go SDK Coming soon, and MCP server Coming soon authenticate with it too.

Manage tokens

• Expiry. Give a token an expiry when you create it, or leave it non-expiring. An expired token stops authenticating on its own.
• Last used. Each token records when it last authenticated a request, so you can spot and prune stale credentials.
• Revoke. Revoke a token from the Tokens page at any time. Revocation takes effect immediately — any service or pipeline using it loses access at once.