Skip to main content
Every Tolmo API request carries a bearer token in the Authorization header:
A request with no token, an unknown token, or an expired token returns 401.

​
Token types

Tolmo issues two kinds of API token. You can tell them apart by their prefix.

​
User tokens (usr_tok.)

A user token represents you. It resolves your permissions on every request, so it sees exactly what you see in the app — no more. Get one by logging in with the CLI:
The token is stored in your profile under ~/.tolmo/. Read it from there, or set it explicitly with the TOLMO_API_TOKEN environment variable. User tokens are deliberately short-lived:
  • They expire seven days after they are minted.
  • They also expire after three days of inactivity, whichever comes first.
Both windows are evaluated against the database clock, so a token cannot be extended by a client with a skewed clock. When a token lapses, run tolmo auth login again.

​
Org API tokens (api_tok.)

An org API token is scoped to one organization rather than to a person, which is what you want for automation — it keeps working when the person who created it changes roles or leaves. An org admin creates one under Settings → API tokens in the Tolmo app. The token is shown once, at creation — copy it then, because it cannot be retrieved afterwards. Supply it along with your org slug:
An org API token is not scope-narrowed — it can reach any /api/v1 endpoint for its organization, and never another organization’s data. What it may do there is still governed by role: a token created this way carries ordinary member permissions, so it can read published findings and create drafts, but it cannot publish one. The broader-role tokens Tolmo’s own agent runs use are minted by the platform and are not something you create.
Tokens created before this credential was renamed begin with org_tok. instead. They remain valid and need no action — authentication is by a hash of the whole token, so the prefix is only a label.
Store org API tokens in your CI provider’s secrets vault. Never commit one to source control or paste it into a workflow file — a leaked api_tok. is valid for your whole organization until it is revoked.

​
What a token can see

Authorization is enforced at the data layer, not only in the route handler, so a token cannot reach around the API to read data it should not see — including through the SQL and openCypher query endpoints. Two consequences worth designing around:
  • Findings that are still drafts are not visible to ordinary callers. You will see published findings, plus ingested ones.
  • A resource in an organization your token cannot access returns 404, never 403. The API will not confirm that a resource exists in an org you cannot see.

​
Revoking a token

Revoke the user token you are currently authenticated with:
This deletes the token’s record, so the bearer stops working immediately rather than waiting for its natural expiry. Org API tokens are revoked under Settings → API tokens. Revocation is recorded rather than deleted, so the list stays an audit trail of what was issued and what happened to it. If you believe a token has leaked, revoke it first and investigate afterwards — revocation takes effect on the next request.

​
Choosing between them

Use a user token

You are exploring the API, writing a script you run yourself, or want every call attributed to you and limited to your own access.

Use an org API token

The caller is a pipeline, a server, or a scheduled job that must keep running unattended and outlive any one person’s account.