> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate to the Tolmo API with Bearer Tokens

> Choose between user tokens and organization tokens, send them as bearer credentials, and understand how each type expires and is revoked.

Every Tolmo API request carries a bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.tolmo.com/api/v1/orgs/acme/findings \
  -H "Authorization: Bearer $TOLMO_API_TOKEN"
```

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.

| Prefix     | Type          | Acts as                        | Use it for                                  |
| ---------- | ------------- | ------------------------------ | ------------------------------------------- |
| `usr_tok.` | User token    | You, with your own permissions | Local development, scripts you run yourself |
| `api_tok.` | Org API token | The organization, not a person | CI pipelines, servers, scheduled jobs       |

### 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:

```bash theme={null}
tolmo auth login
```

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:

```bash theme={null}
export TOLMO_API_TOKEN="api_tok...."
export TOLMO_ORG_SLUG="acme"
```

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.

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
tolmo auth logout
```

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

<CardGroup cols={2}>
  <Card title="Use a user token" icon="user">
    You are exploring the API, writing a script you run yourself, or want every call attributed to you and limited to your own access.
  </Card>

  <Card title="Use an org API token" icon="robot">
    The caller is a pipeline, a server, or a scheduled job that must keep running unattended and outlive any one person's account.
  </Card>
</CardGroup>