CLI Authentication

The CLI supports browser-based user authorization and project API keys. Local profiles store the selected credential, API origin, OTLP origin, and default project context.

View as Markdown Open the plain-text version of this page.

Prerequisites#

The provon binary on PATH.
For browser login: a browser on the same machine and reachability to the configured API origin.
For API keys: a project id and a key created in the Workbench or with provon api-keys create.

provon auth login

The command starts a loopback callback server on 127.0.0.1, opens the browser for authorization, exchanges the code for a user-access credential, and stores it in the active profile. Use --no-open to print the authorization URL instead of opening a browser.

--profile <name>      Profile name
--timeout-ms <ms>     Maximum time to wait for browser authorization (default 120000)
--no-open             Print the authorization URL instead of opening a browser

Inspect or remove the profile:

provon auth status
provon auth logout

auth status reports authenticated, the resolved API URL, active project id, credential type (user_access or project_api_key), and the profile source.

Project API Key#

Use an API key for service automation and CI:

provon auth token set \
  --api-key "$PROVON_API_KEY" \
  --project "$PROVON_PROJECT_ID"

--api-key <key>    Provon project API key
--project <id>     Default project id for workspace-scoped routes
--profile <name>   Profile name

Capability Requirements#

The key's capabilities determine which commands can run. A key created without an explicit capability list receives the default set:

Default capability	Covers
`telemetry:ingest`	OTLP uploads from `ingest sync` and live hooks
`telemetry:read`	`traces list`, `get`, `overview`, `stats`, conversations, users
`diagnostics:read`	`findings list/get/events`, `findings rules list/get`
`gateway:invoke`	Proxied Gateway requests
`model-pricing:read`	Model pricing lookups used by Gateway responses
`workspace:read`	Organization and project read commands

Additional grantable capabilities: diagnostics:write, gateway:manage, mcp:invoke, mcp:manage, model-pricing:write, workspace:write, models:manage. For example, Finding review updates and handoffs require diagnostics:write; Gateway provider administration requires gateway:manage; federated MCP tool calls require mcp:invoke. See API keys for creating keys and usage policies.

Project Context#

List available projects and select the default for the active profile:

provon workspace projects list
provon project use <project-id>
provon project current

Project-qualified Workspace routes require a selected project, supplied by project use, the --project flag, or PROVON_PROJECT_ID.

Resolution Order#

Per setting:

Setting	Flag	Environment variable	Profile field	Built-in default
API key	`--api-key`	`PROVON_API_KEY`	`credential`	none
Project id	`--project`	`PROVON_PROJECT_ID`	`projectId`	none
API origin	none	`PROVON_API_URL`	`apiUrl`	`https://api.provon.dev`
OTLP traces origin	none	`PROVON_OTEL_URL`	`otelUrl`	derived from API origin
Profile name	`--profile`	`PROVON_PROFILE`	`default`	`default`

The profile file lives at ~/.config/provon/config.json (override with XDG_CONFIG_HOME or PROVON_CONFIG_FILE). Browser access tokens refresh automatically; a failed refresh requires provon auth login again.

Note

ingest hooks install reads credentials from the --project / --api-key flags or the active profile only; it does not read PROVON_API_KEY / PROVON_PROJECT_ID from the environment. Run provon auth token set first when using a key outside an interactive shell.

Configure Origins#

provon config get
provon config get api-url
provon config set api-url http://127.0.0.1:3000
provon config set otel-url http://127.0.0.1:3000/v1

Supported settings are api-url and otel-url. When otel-url is unset, the OTLP traces URL is derived from the API origin: the hosted default resolves to https://otel.provon.dev/v1, and a custom API origin gets /v1/traces appended when the path does not already end in /traces.

Success Check#

provon auth status

A healthy result shows authenticated: true, the expected apiUrl, and a non-empty projectId when project-scoped commands are planned.

Troubleshooting#

Symptom	Likely cause	Fix
`auth.missing_credential`	No profile credential and no `--api-key`	`provon auth login` or `provon auth token set`
`auth.session_expired`	Refresh token expired or invalid	Run `provon auth login` again
`auth.login_timeout`	Browser authorization not completed within the timeout	Re-run with `--timeout-ms 180000`, or use `--no-open` and open the URL manually
`auth.invalid_callback`	Callback state mismatch or blocked redirect	Close other browser sessions for the same origin and retry
`HTTP_403` on traces/findings	Key missing `telemetry:read` / `diagnostics:read`	Create a key with the required capabilities
`MISSING_PROJECT_ID`	No active project	`provon project use <id>` or pass `--project <id>`
Wrong origin after install	Profile points at the hosted default	`provon config set api-url <self-hosted-url>`