The short version

curl https://kumo.io/api/tenants/<workspace-address>/v1/accounts/<account-id>/workspaces \
  -H "Authorization: Bearer <your-token>"

Every API request carries an Authorization: Bearer <token> header. API tokens are included from the Team plan.

Where to send requests

Paths start with /v1. Almost every path is scoped to your account: /v1/accounts/<account-id>/…. You can find your account ID in Settings → Profile & Security, under Account.

Create a token

1. Open Settings → API Tokens.
2. Enter a Token name that says what the token is for, for example ci-pipeline.
3. Choose its Access: Read Only (the default) or Read and Write.
4. Choose when it Expires: in 7, 30, 90 (the default) or 180 days, or in 1 year. Every token expires; one year is the longest.
5. Choose Create Token.
6. Kumo.io shows the token's secret once: "Copy this secret now — it is shown exactly once and cannot be retrieved again." Choose Copy Token Secret, store it in your password manager or secret store, then choose I've copied it — dismiss.

Kumo.io stores only a hash of the secret. If you lose it, create a new token.

The token you send

A token has two parts joined by a dot: its prefix and its secret.

kum_<10 characters>.<64 characters>

The prefix starts with kum_ and is shown next to the token's name in the token list (followed by …). Send the whole thing, prefix, dot and secret:

Authorization: Bearer kum_0a1b2c3d4e.<secret>

The secret on its own does not authenticate. If Copy Token Secret gave you only the 64-character secret, put the token's prefix and a dot in front of it.

What a token can do

A token acts as the person who created it. A Read and Write token has exactly that person's roles in the account, so it can do what they can do in the app, and nothing more. A Read Only token can read what they can read and change nothing: any request other than GET or HEAD is refused with 403. See What can each role do? and API tokens.

A token only works in its own account. A request for another account's path is refused.

Revoke a token

In Settings → API Tokens, choose Revoke next to the token, then Revoke Token. It stops authenticating immediately, so anything using it (CI, scripts, CLI sessions) starts failing. Each token in the list shows its status, when it expires and when it was last used, which helps you find tokens nobody uses.

Authentication errors

For the error format, see What do responses, pages and errors look like?

Use a token with the CLI

The kumo CLI works against the API when you give it an API URL:

The flag wins when both are set. These flags go before the subcommand. Set your account with KUMO_ACCOUNT or the command's own account option:

export KUMO_API_URL=https://kumo.io/api/tenants/<workspace-address>
export KUMO_API_TOKEN=<your-token>
kumo workspace list --scope-account <account-id>

In remote mode, select things by ID rather than by name. Only commands that support remote mode run; others stop with a "local-only" error. See the CLI reference.

Use a token with an MCP client

kumo mcp serve runs a read-only MCP server over your Kumo.io data, for AI assistants that support the Model Context Protocol. Point your MCP client at:

kumo mcp serve --api-url <api-base-url> --token <your-token> --account <account-id>

or set KUMO_API_URL, KUMO_API_TOKEN and KUMO_ACCOUNT.

Keep tokens safe

• Create one token per script, pipeline or tool, with a name that says which. Revoking one then affects only that consumer.
• Set an expiry so forgotten tokens can't linger. To rotate, create a replacement, switch your scripts to it, then revoke the old one.
• Keep tokens in a secret manager and pass them as environment variables. Never put a token in source code or a repository.
• Review your tokens when people change roles or leave, and revoke the ones they created.