# 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](./self-hosting-configuration.md#sign-in-providers) for the exact
environment variables and callback URLs.

## Related Pages

- [API reference](./api-reference.md)
- [Gateway API](./gateway-api.md)
- [OTLP/HTTP API](./otlp-api.md)
- [Self-hosting security](./self-hosting-security.md)