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, Go SDK, and headless use of the remote MCP server authenticate with it too.

You do not need a token to connect an agent interactively: an agent reaches the remote MCP server by URL and you authorize it in the browser with Sign in with Koo. That authorization is confined the same way a token is — one account, Read or Write — and you revoke it from the console's Connections page rather than the Tokens page.

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.