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

​
Get an API key

An API key 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.
1

Open API keys

Go to API keys in the Tolmo app (Settings → API keys).
2

Create a key

Click Create key. Give it a name you will recognize later, such as the pipeline or service that will use it.
3

Copy it immediately

The key is shown once, at creation. Copy it then — it cannot be retrieved afterwards.
4

Send it on every request

Export it with your org slug, then pass it as a bearer credential:
An API key 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 key created this way carries ordinary member permissions, so it can read published findings and create drafts, but it cannot publish one. The broader-role credentials Tolmo’s own agent runs use are minted by the platform and are not something you create.
Keys created before this credential was renamed begin with org_tok. instead of api_tok.. They remain valid and need no action — authentication is by a hash of the whole value, so the prefix is only a label.
Store API keys 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.

​
Credential types

Tolmo issues two kinds of credential. 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.

​
What a credential can see

Authorization is enforced at the data layer, not only in the route handler, so a credential 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.
  • An /orgs/{orgSlug}/... path for any organization other than your own is rejected. Inside your own organization, a resource id you cannot see returns 404 — the API will not confirm that it exists elsewhere.

​
Revoking a credential

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. API keys are revoked under API keys in Settings. 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 key has leaked, revoke it first and investigate afterwards — revocation takes effect on the next request.

​
Choosing between them

Use an API key

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

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.