Authentication
Provon uses two authentication paths:
| 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.