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

## Related Pages

- [API reference](./index.md)
- [Gateway API](./gateway.md)
- [OTLP/HTTP API](./otlp.md)
- [Model Pricing API](./model-pricing.md)
- [Self-hosting security](../self-hosting/security.md)