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 workflow operations.

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

Capability Typical use
telemetry:ingest OTLP exporters and provon sync uploads
telemetry:read Trace API and CLI trace queries
gateway:invoke Model inference through the Gateway
workspace:read Gateway discovery and configuration reads
gateway:manage Provider Key and model mapping writes
diagnostics:read Finding and Rule inspection
diagnostics:write Rule updates, Run scheduling, review updates, and repair handoff

Do not expose project API keys in browser code.

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 exact Workbench 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_*;
  • SAML through AUTH_SAML_*.

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