The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
# CLI Authentication
import { Callout } from "nextra/components";
The `traceway` CLI and the dashboard share the same accounts, but the CLI signs in with its own OAuth-style flows rather than storing your dashboard password. There are three ways to log in, plus long-lived **personal access tokens** for automation.
## Browser device login (default)
Running `traceway login` with no flags starts a [device authorization](https://datatracker.ietf.org/doc/html/rfc8628) flow:
```
traceway login ──► POST /api/auth/device/authorize
└─► CLI prints a URL + short code (XXXX-XXXX)
└─► you open the URL, sign in, approve the code at /device
└─► CLI polls POST /api/auth/device/token (grant device_code)
└─► receives a 15-min access token + a rotating
90-day refresh token, stored locally (0600)
```
The CLI refreshes the access token automatically when it expires, rotating the refresh token each time. You stay logged in for up to 90 days of inactivity without re-entering anything.
A `traceway login` is always read only. The separate `traceway-write` CLI runs the same flow under its own client id, and the approval page tells you it asks for read and write access. See [Agent Write Access](/learn/agent-write-access).
The device flow needs an interactive terminal (someone has to approve the code). In CI or scripts, use a personal access token or password login instead; on a headless box you can pass `--no-browser` and approve the code from another device.
## Password login
```bash
traceway login --password # prompts for email + password
traceway login --username [email protected] # implies --password
traceway login --password-stdin # reads the password from stdin
```
The CLI asks for a token scoped to itself, so a `traceway --password` login is read only and cannot be used as a dashboard session. Like a browser login it is a short-lived access token that the CLI refreshes automatically, and `traceway logout` revokes it on the server. (Against a Traceway server older than agent scopes, a password login is a 7-day token that is not refreshable.)
## Personal access tokens
Create a token from the dashboard (**Account → Personal access tokens**), then:
```bash
traceway login --token twp_xxxxxxxxxxxx
# or
echo "twp_xxxxxxxxxxxx" | traceway login --token-stdin
```
PATs are the right choice for CI and long-running automation. They're shown once at creation, carry an optional expiry, and can be revoked at any time from the same dashboard page.
A token has an access level:
- **Read only** (`twp_`, the default) reads telemetry, monitors, pages, alerts and post-mortems. It never changes anything.
- **Read and write** (`tww_`) can also make the changes listed in [Agent Write Access](/learn/agent-write-access), in organizations where an admin turned agent writes on. It must expire within 90 days.
Tokens only reach the API routes the CLI and MCP server use. Account, member, token and settings routes refuse them, so a leaked token cannot mint another token or approve a login.
## Logging out
```bash
traceway logout
```
For device logins this revokes the refresh-token family server-side (so it can't be refreshed again) and then removes the local credentials. Revoking a PAT is done from the dashboard.
## Self-hosting: configuring authentication
The CLI and MCP device flow work against any Traceway instance with no extra setup; the endpoints are always registered. Two server settings shape whether it is safe and where the login URLs point.
### Set a strong `JWT_SECRET`
<Callout type="warning">
`JWT_SECRET` is what makes authentication safe. It signs **every** token the server issues: dashboard sessions and the short-lived access tokens the CLI and MCP server receive from the device flow. Anyone who knows it can forge a valid token for any user and take over any account. Set it to a strong, unique value you keep out of source control, and **never expose an instance that is still using a default**.
</Callout>
Generate one and pass it as an environment variable:
```bash
openssl rand -hex 32 # use the output as JWT_SECRET
```
- Minimum length is 32 characters; the server refuses to start with a shorter secret.
- **Every server image, including All-in-One, requires `JWT_SECRET`.** Former built-in keys are rejected. Older All-in-One images overwrote Docker-provided secrets; upgrade and recreate those containers with a unique key. See the [All-in-One upgrade note](/server/all-in-one#environment-variables).
- Keep it **stable**. Rotating it logs out active dashboard sessions (users sign in again). CLI logins and personal access tokens are opaque, database-backed credentials, so those keep working: a CLI simply refreshes into a token signed with the new secret on its next call.
`OAUTH_SESSION_SECRET` falls back to `JWT_SECRET` when unset; set it separately only if you want to rotate the OAuth cookie secret independently.
### Set `APP_BASE_URL` to your public origin
`APP_BASE_URL` becomes the OAuth **issuer**, the base of the device-login verification URL the CLI prints, and the origin advertised in the discovery documents below. If it is unset the server derives the origin per-request from the `Host` / `X-Forwarded-*` headers, which is fine for direct access. Set it explicitly when the server sits behind a proxy that rewrites the `Host` header, so the printed URL points where users can actually reach it.
### Discovery endpoints
Spec-compliant clients, including the MCP server, self-configure from two documents served at the origin root, so you never hard-code endpoints:
- `GET /.well-known/oauth-authorization-server`: [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) authorization-server metadata (issuer, token and device-authorization endpoints, supported grants).
- `GET /.well-known/oauth-protected-resource`: [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) protected-resource metadata.
Both derive their URLs from `APP_BASE_URL` (or the request headers when it is unset). No additional configuration is required.