Skip to content

Authentication

Provon uses two authentication paths:

View as Markdown Open the plain-text version of this page.
Path Used by Credential
Project API key Agents, exporters, CLIs, automation, and server workloads Authorization: Bearer <PROVON_API_KEY>
Browser session Signed-in Workbench users AuthJS session cookie

Provider credentials, connector tokens, and upstream model keys are not Provon API credentials. They remain attached to provider or connector configuration and must not be sent as Gateway or OTLP client credentials.

Project API Keys#

Use project API keys for machine traffic:

  • OTLP ingest;
  • Trace, log, metric, conversation, and user reads;
  • Gateway inference and Gateway discovery;
  • Diagnostics reads and writes;
  • CLI commands such as provon sync, provon traces, and API-backed diagnostics.

Each key carries capabilities. Grant only the capabilities required by the workload:

Capability Default Typical use
telemetry:ingest Yes OTLP exporters and provon sync uploads
telemetry:read Yes Trace, log, metric, conversation, and user queries
gateway:invoke Yes Model inference through the Gateway
gateway:manage No Provider Key and model mapping writes
model-pricing:read Yes Resolved model prices and match checks
model-pricing:write No Project price overrides
diagnostics:read Yes Finding, Rule, and settings inspection
diagnostics:write No Rule updates, Runs, review updates, and repair handoff
workspace:read Yes Project and Gateway discovery
workspace:write No Supported project configuration writes
models:manage No Node-only model runtime management

Do not expose project API keys in browser code.

Create And Rotate Keys#

In the Workbench, open API keys in the project, create a key, and copy its secret immediately. The complete secret is shown once.

Use separate keys for independent workloads:

  • one ingest key for each exporter or environment;
  • one Gateway invocation key for each application boundary;
  • one read key for CI or analysis;
  • one narrowly scoped write key for controlled automation.

To rotate a key:

  1. create a replacement with the same minimum capabilities;
  2. deploy it to the client;
  3. verify a real request;
  4. revoke the old key.

Revocation is immediate for new requests. Never put a key in trace attributes, connector configuration fields, or GitHub Issue bodies.

Public And Project-Qualified Paths#

Project API keys can use public paths such as:

text
GET /v1/traces
GET /v1/model-prices

The key selects the project. Signed-in Workbench clients use project-qualified paths such as /v1/projects/:projectId/traces. Service integrations should prefer public paths where the domain provides them.

Browser Sessions#

Workbench sign-in uses AuthJS-backed browser sessions. Browser sessions are for human UI access and project-qualified application routes. They are not OTLP credentials and should not be used by exporters or agent workloads.

Self-Hosted Secrets#

Production self-hosted deployments need a stable AUTH_SECRET. PROVON_AUTH_SECRET is an equivalent fallback, but use one canonical name per deployment. All runtimes that read the same metadata store must use the same secret because sessions and stored credentials depend on it.

Configure the exact OAuth callback origin with PROVON_AUTH_ORIGIN and exact browser origins with PROVON_WORKBENCH_ORIGINS. When splitting API and Workbench origins across subdomains, set PROVON_AUTH_COOKIE_DOMAIN to the shared parent domain and set PROVON_AUTH_TRUST_HOST=true only behind a trusted ingress that overwrites forwarded headers.

Identity Providers#

Self-hosted deployments can configure AuthJS providers through environment variables:

  • GitHub, Google, and Apple OAuth;
  • generic OIDC through AUTH_OIDC_*.

See Self-hosting configuration for the exact environment variables and callback URLs.