What a token can do

A token acts as the person who created it, and every token has an access level you choose when you create it:

A token never has more access than you. If your access changes, every token you created changes with it. Choose Read Only unless the job really makes changes. A few read-only queries are sent as POST (an environment query preview, change correlation); they need a Read and Write token.

Every token expires. The default is 90 days and the longest is one year; there is no token that never expires.

Kumo.io stores only a hash of each token. The secret is shown once, when you create the token.

API access is included in the Team, Business and Enterprise plans on hosted Kumo.io, and in Enterprise (Licensed) on a self-hosted installation.

Create a token

1. Open Settings › API Tokens.
2. Enter a Token name that says where it will be used, 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.
5. Select Create Token.
6. Copy the token straight away with Copy Token. It is the full bearer value, kum_<…>.<secret>, and it is shown exactly once and can't be retrieved again.

The new token then appears in the list with its prefix, which starts kum_, its status, its access level, its expiry, when it was last used, and who created it.

With the API, POST /v1/accounts/{accountId}/api-tokens takes displayName, a required scope (read or read_write) and an optional expiresAt (ISO-8601, at most 365 days out; omitted means 90 days). The CLI equivalent is kumo token create --display-name <name> --scope <read|read_write> [--expires-at <iso>].

Use a token

Send the token in the Authorization header:

curl "$KUMO_API_URL/v1/accounts/$KUMO_ACCOUNT/workspaces" \
  -H "Authorization: Bearer $KUMO_API_TOKEN"

The bearer value is the token's prefix and its secret joined by a dot: kum_<…>.<secret>. The prefix is the kum_… value shown in the token list.

You also need two values:

Every request path that names an account must name the token's own account. A token from one account can't reach another account's data.

Use a token with the CLI

The kumo CLI uses a token to run commands against a Kumo.io installation's API instead of a local engine. Prefer environment variables, so the token doesn't end up in your shell history or process list:

export KUMO_API_URL=https://kumo.example.com
export KUMO_API_TOKEN=kum_<…>.<secret>
export KUMO_ACCOUNT=<account id>

The same values can be passed as --api-url, --token and --account. The MCP server uses these settings too. Read the CLI reference for the commands.

Who sees which tokens

• Everyone sees the tokens they created.
• People with the iam.api_key.read permission see every token in the account. The Account owner and Account admin roles include it.
• You can always revoke your own tokens. Revoking someone else's needs iam.api_key.write, which the Account owner and Account admin roles include.
• A Read Only token can't create or revoke tokens, so it can't be used to make itself a stronger one.

Revoke a token

1. Open Settings › API Tokens.
2. Select Revoke next to the token, then Revoke Token to confirm.

The token stops authenticating immediately. Anything still using it, such as a CI job, a script or a CLI session, starts failing.

Rotate a token

Kumo.io doesn't rotate tokens for you, so do it yourself before a token expires:

1. Create a replacement token.
2. Switch your CI jobs and scripts to the new token.
3. Revoke the old one.

Every token expires, so a forgotten one can't linger more than a year. Because a token acts as the person who created it, a change to that person's roles changes what their automation can do too.

Creating and revoking tokens are recorded in the audit log.