---
title: "Authentication"
canonical: https://trickest.com/docs/developer-tools/cli/authentication
description: "How the trickest CLI authenticates: API tokens, the TRICKEST_TOKEN environment variable, login, and identity checks."
---

# Authentication

Every CLI command acts as **you**, scoped to your active **vault** (your
organization/workspace). The CLI proves who you are with an **API token**.

## Token precedence

The CLI resolves your token in this order, the environment variable always wins:

1. **`TRICKEST_TOKEN` environment variable**, preferred for agents, scripts, and CI.
2. **Stored credentials** written by `trickest auth login`.

```bash
export TRICKEST_TOKEN="your-api-token"
```

<Tip>
Get an API token from **Settings > Personal > API & apps** in the Trickest web app. Treat it
like a password, anyone with it can act as you.
</Tip>

## `trickest auth`

Manage authentication.

### `trickest auth status`

Report whether you're authenticated and where the token came from.

```bash
trickest auth status
```
```json
{"authenticated":true,"source":"TRICKEST_TOKEN env var","email":"you@org.com","vault":"your-vault"}
```

The `source` field tells you whether the active token is from the `TRICKEST_TOKEN env var` or stored config, useful when an environment token overrides your saved login. Missing or rejected credentials return exit code 2. If the server cannot be reached, status reports `authenticated: "unknown"` and cached identity; that response is not proof that authentication succeeded.

### `trickest auth whoami`

Resolve your identity against the backend.

```bash
trickest auth whoami
```
```json
{"email":"you@org.com","vault":"your-vault","source":"env","live":true}
```

`"live": true` means the CLI actually round-tripped the token to the server (not just read it locally), so a `true` here is a real connectivity + validity check.

### `trickest auth login`

Authenticate interactively and store the token for future commands.

```bash
trickest auth login                       # authorize in your browser
trickest auth login --device              # use the printed code on another device
trickest auth login --token-file ./token  # read an API token from a file
```

On a headless host, login prints a URL and one-time code without opening a browser.
Interactive login is disabled in CI unless you explicitly select a device flow.
Use `TRICKEST_TOKEN` or `--token-file` for automation. The older `--token` flag is
deprecated because command arguments can be visible in process listings.

You do **not** need to run `login` if `TRICKEST_TOKEN` is set, the env var is used directly.

### `trickest auth logout`

Clear stored credentials.

```bash
trickest auth logout
```

This only affects stored credentials; it does not unset `TRICKEST_TOKEN` in your shell.

## Confirming your user identity

`auth whoami` reports the email/vault. For the canonical user record (including the numeric user id), use:

```bash
trickest users me
```
```json
{"id":214,"email":"you@org.com","username":"you"}
```

## Vaults

Your **vault** is the scope every command operates within. It is resolved from your
token automatically and stored as `auth.vault_id` in the CLI config:

```bash
trickest config get auth.vault_id
# {"key":"auth.vault_id","value":"<vault-id>"}
```

You rarely set this by hand; the token determines it. See
**[Configuration & Context](/docs/developer-tools/cli/configuration)** for the full
config model.

## Troubleshooting

<AccordionGroup>
  <Accordion title="ERR_AUTH: Invalid token (exit code 2)">
    The token is missing, malformed, or rejected. Re-export `TRICKEST_TOKEN` or run
    `trickest auth login`. Confirm with `trickest auth status`.

    Note: a handful of commands (for example `billing`) may be **separately gated**
    and can return `ERR_AUTH` even when the same token works everywhere else. If
    `space ls` / `users ls` succeed but one command reports an auth error,
    check that command's access requirements and the returned error. A successful request elsewhere does not identify the cause of every authentication failure.
  </Accordion>
  <Accordion title="auth status says authenticated but commands fail">
    Check `trickest status` for the selected backend and `trickest auth status`
    for a live credential check. Also inspect the failing command's permission
    and validation error. Change `TRICKEST_BASE_URL` only if it points to the
    wrong deployment; an authenticated request can still lack permission for an operation.
  </Accordion>
  <Accordion title="Device authorization failed / Unable to connect">
    The CLI could not reach the platform. Confirm network access to
    `https://trickest.io`, then retry `trickest auth login`.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Configuration & Context" icon="gear" href="/docs/developer-tools/cli/configuration">
    The config file, active space/workflow context, and base URL.
  </Card>
  <Card title="Output & Exit Codes" icon="circle-exclamation" href="/docs/developer-tools/cli/output-and-exit-codes">
    The full error envelope and exit-code contract (incl. ERR_AUTH).
  </Card>
</CardGroup>

---
_Markdown source of https://trickest.com/docs/developer-tools/cli/authentication._