> ## 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 an API key

> Create an API key in the Tolmo app, send it as a bearer credential, and understand how keys and user tokens expire and are revoked.

Every Tolmo API request carries a bearer credential 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 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](https://app.tolmo.com/settings/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:

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

An API key is scoped to its organization. Endpoint-specific permissions still apply, and user-only endpoints reject API keys. For example, a key created this way carries ordinary member permissions, so it can read published findings and create drafts, but it cannot publish one. Evidence attachments and user membership endpoints require a user token.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> 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.

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

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

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

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

Logout attempts server-side revocation and clears the local cache. If revocation fails, the CLI prints a warning; clearing the cache alone does not invalidate the remote token.

API keys are revoked under [API keys](https://app.tolmo.com/settings/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

> [card] 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](https://app.tolmo.com/settings/api-keys).

> [card] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.