> ## 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 the Tolmo CLI

> Sign in with a browser for interactive use, or use an organization API key for automation.

Use browser login for interactive work. For CI and services, create an API key under **Settings → API keys** and pass it through `TOLMO_API_TOKEN`.

## Sign in

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

Login opens your browser and asks you to select an organization if you belong to more than one. It saves a user token (`usr_tok.*`) and the selected organization in the active profile. The default profile is `default`.

To print the login URL without opening a browser:

```bash theme={null}
tolmo auth login --no-browser
```

You still need to complete the browser flow. Use an API key for unattended jobs.

`tolmo auth status` shows the effective profile, API URL, organization, and the source of each setting. It also shows the credential type and a shortened token prefix.

## Select an organization

```bash theme={null}
tolmo org list
tolmo org switch acme
tolmo --org other-org findings list
```

`org switch` saves your choice in the active profile. `--org` applies to one invocation. A user token can access the organizations you belong to without a separate login for each one.

## Use a named profile

```bash theme={null}
tolmo auth login --profile work --api-url https://api.tolmo.com
tolmo --profile work findings list
```

Set `TOLMO_PROFILE=work` to select that profile for your shell. See [Profiles](https://docs.tolmo.com/configuration/profiles.md) for credential storage and logout behavior.

## Use an API key

Create a key in [**Settings → API keys**](https://app.tolmo.com/settings/api-keys). Store it in your environment or CI secret store:

```bash theme={null}
export TOLMO_API_TOKEN="your-api-key"
export TOLMO_ORG_SLUG="acme"
tolmo findings list --status open --json
```

When `TOLMO_API_TOKEN` is set, the CLI skips profile configuration and cached credentials. Set the organization with `TOLMO_ORG_SLUG` or `--org`. The API URL comes from `TOLMO_API_URL`, or defaults to `https://api.tolmo.com`.

API keys are scoped to one organization. `--org` cannot expand a key's access. User-specific operations such as listing your memberships and managing evidence attachments require a user token.

Unset `TOLMO_API_TOKEN` before running `tolmo auth login`. `tolmo org switch` is unavailable while this variable is set; change `TOLMO_ORG_SLUG` instead.

## Sign out

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

Logout attempts to revoke the cached user token and clears the local credential even if server revocation fails. In that case, the CLI prints a warning. The profile's API URL and organization remain saved.

Logout does not revoke an API key supplied through the environment. Revoke API keys in **Settings → API keys**.

User tokens expire after seven days or three days of inactivity. Run `tolmo auth login` again when your session expires. See [API authentication](https://docs.tolmo.com/api-reference/authentication.md) for credential permissions.


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