CLI Authentication

The tracepath 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.

The CLI itself is not distributed yet, so the tracepath login flows below describe how it will authenticate. Personal access tokens are available today and work over plain HTTP against https://app.tracepath.dev — that section is the one to read if you are scripting against TracePath now.

Browser device login (default)

Running tracepath login with no flags starts a device authorization (opens in a new tab) flow:

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

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

tracepath login --password                  # prompts for email + password
tracepath login --username [email protected]  # implies --password
tracepath login --password-stdin            # reads the password from stdin

Password logins are not refreshable: when the token expires you log in again.

Personal access tokens

Create a token from the dashboard (Account → Personal access tokens), then:

tracepath login --token tpp_xxxxxxxxxxxx
# or
echo "tpp_xxxxxxxxxxxx" | tracepath login --token-stdin

PATs are the right choice for CI and long-running automation, because nothing about them needs a browser. They are shown once at creation — the dashboard stores only a hash and a 12-character prefix for identification — carry an optional expiry of 1 to 3650 days, and can be revoked at any time from the same page.

A tpp_-prefixed token is accepted anywhere the API accepts a dashboard session token: send it as Authorization: Bearer tpp_…. It carries the full permissions of the user who created it, so scope it by creating it under an account whose project role is already limited to what the automation needs.

⚠️

A personal access token is a password. Keep it in your CI provider's secret store, never in a repository, a Dockerfile, or a URL. Revoke it from Account → Personal access tokens the moment a job that used it is retired.

Tokens can also be managed over HTTP:

# create
curl -sS -X POST https://app.tracepath.dev/api/personal-access-tokens \
  -H "Authorization: Bearer $TRACEPATH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-deploy","expiresInDays":90}'
 
# list (prefixes only, never the secret)
curl -sS https://app.tracepath.dev/api/personal-access-tokens \
  -H "Authorization: Bearer $TRACEPATH_TOKEN"
 
# revoke
curl -sS -X DELETE https://app.tracepath.dev/api/personal-access-tokens/<id> \
  -H "Authorization: Bearer $TRACEPATH_TOKEN"

The create response is the only place the token field ever appears. A name is required and must be 100 characters or fewer; expiresInDays is optional and must be between 1 and 3650. Both rules answer 422 with an error message when broken.

Logging out

tracepath 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, or with the DELETE call above.

Discovery endpoints

Spec-compliant OAuth clients, including MCP clients, self-configure from two documents served at the origin root, so nothing hard-codes an endpoint:

GET https://app.tracepath.dev/.well-known/oauth-authorization-server: RFC 8414 (opens in a new tab) authorization-server metadata (issuer, token and device-authorization endpoints, supported grants).
GET https://app.tracepath.dev/.well-known/oauth-protected-resource: RFC 9728 (opens in a new tab) protected-resource metadata.

Both are public and need no credentials.

Signing In: the dashboard side — password, Google, and GitHub.
MCP Server: the same credentials from an MCP client.

CLI MCP Server