# Authentication

> Source: https://truto.one/docs/cli/authentication/

The CLI uses **API tokens** exclusively — not your dashboard email and password. Each token is a Bearer credential scoped to **one** Truto environment (`development`, `staging`, or `production`).

## Get an API token

Create a token in the dashboard before running `truto login`:

1. Sign in to [app.truto.one](https://app.truto.one).
2. Go to **Settings → API Tokens**.
3. Click **Create API Token**.
4. Enter a name (for example `cli-macbook` or `ci-staging`) and select the **environment** the token should access.
5. Click **Create API Token**, then **copy the token immediately** — Truto only shows the full secret once.
6. Check **I have copied my API Token** and click **Done**.

![Go to API tokens in Settings](https://docs-assets.truto.one/create-api-token.png)

![Copy API Token](/images/docs/api-tokens/api-token-generated.png)

Store the token in a password manager or export it to your shell for non-interactive login:

```bash
export TRUTO_API_TOKEN="<paste-token-here>"
```

:::callout{type="warning"}
Treat API tokens like passwords. Anyone with the token can call Truto Admin and data-plane APIs as your team in that environment. Do not commit tokens to git or paste them in public channels.
:::

**Environment matters:** A `staging` token cannot list production accounts or integrations. Pick the environment you intend to work in when creating the token. Read more in [Environments overview](/docs/guides/environments/overview).

**CLI vs dashboard:** You can **list** and **view** tokens with `truto api-tokens list` and `truto api-tokens get <id>`, but **creating and deleting** tokens must be done in the dashboard (or via the Admin API from your own backend).

## Interactive login

```bash
truto login
```

You are prompted for:

1. **Profile name** (default: `default`) — a local label so you can switch between staging and production profiles later
2. **API base URL** (default: `https://api.truto.one`) — leave as-is unless your team gave you a different API host
3. **API token** (masked input) — paste the token you copied from **Settings → API Tokens**

The token is verified against the API before saving. If a profile with the same name already exists, you are asked to confirm overwriting it (use `-f` to skip).

## Non-interactive login

```bash
truto login --token <your-api-token>

# Custom API URL
truto login --token <token> --api-url https://your-instance.truto.one

# Named profile
truto login --token <token> --profile-name staging

# Overwrite without confirmation
truto login --token <token> --profile-name staging -f
```

:::callout{type="info"}
When using `--token`, interactive prompts are skipped and existing profiles are overwritten without confirmation (same as `-f`).
:::

## Logout and verify

```bash
# Remove credentials (default profile)
truto logout

# Remove a specific profile
truto logout --profile-name staging -f

# Verify current credentials
truto whoami
truto whoami -p staging -o json
```

## Profiles

Credentials are stored in `~/.truto/config.json` (mode `0600` on POSIX). Manage multiple profiles for staging, production, or different teams:

```bash
truto profiles list
truto profiles use staging
truto profiles set api-url https://custom.truto.one
truto profiles set default-integrated-account <account-id>
truto profiles get api-url
```

Store bring-your-own keys for `truto integrations build` (Anthropic, Firecrawl):

```bash
truto profiles set-key anthropic                # interactive, masked
truto profiles set-key firecrawl sk-...          # non-interactive
```

See [AI-powered build](/docs/cli/integrations-build) for how BYOK keys are used.

### Allowed profile keys

| Key                        | Aliases                                                    |
| -------------------------- | ---------------------------------------------------------- |
| `apiUrl`                   | `api_url`, `api-url`                                       |
| `defaultIntegratedAccount` | `default_integrated_account`, `default-integrated-account` |
| `anthropicApiKey`          | `anthropic_api_key`, `anthropic-api-key`                   |
| `firecrawlApiKey`          | `firecrawl_api_key`, `firecrawl-api-key`                   |

## Resolution order

**Token:**

1. `--token` flag (highest priority)
2. Active profile's `apiToken`
3. Error if none found

**API URL:**

1. `--api-url` flag
2. Active profile's `apiUrl`
3. `https://api.truto.one` (default)

Your API token is scoped to a single **environment**. You never pass `environment_id` on commands — all resources are automatically filtered to that environment.

## Next steps

- [Global options](/docs/cli/global-options) — `-p`, `--token`, output formats
- [Managing integrations](/docs/cli/integrations) — first admin commands after login