# API keys and scopes

How to choose project API key scopes and safely give machines access to BernOps.

Project API keys let external systems operate inside one BernOps project without sharing a user session. They are bearer tokens, so treat them like production credentials.

## Choosing the caller

Use a user JWT when a person is using the UI and performing management actions. Use a project API key when a machine needs repeatable access.

Examples of good API-key use cases:

- A CI pipeline executes saved jobs.
- A queue worker claims and completes queue items.
- An external automation job streams logs, steps, metrics, and attachments.
- An MCP server reads project data and triggers approved runs.
- A work-board agent claims Todo work, renews its lease, and submits the result for human review.

## Scopes are capabilities

External SDK writers should use a job-bound `ingest-runner` key with only the required write scopes. See the [Automation SDK external quick start](/docs/automation-sdk#external-quick-start); native Playwright SDK jobs require no API key.

Scopes express what a key may do inside its project. Prefer the narrowest preset that supports the job.

| Preset or scope family | Typical purpose |
| --- | --- |
| `cicd-driver` | Execute existing jobs and read run state from CI. |
| `ingest-runner` | Report external execution logs, steps, metrics, and attachments. |
| `queue-worker` | Read queues, claim items, and report queue progress. |
| `board-agent` | Read and edit project work, acquire fenced claims, and submit work to In Review. |
| `mcp-agent` | Inspect project state and trigger constrained work. |
| `variables:use` | Let API-key initiated runs receive project runtime variables. |

Work-board automation uses `work_items:read` to discover work, `work_items:write` to create or edit planning records, and `work_items:claim` for claim, renewal, release, and submission commands. Work-item status remains independent from execution status.

**Scope names are exact**

If a request returns `Insufficient API key scope`, the key authenticated correctly but does not have the capability required by that endpoint or execution path.


## Runtime variables and keys

The `variables:use` scope is special. It does not let callers read secret values from the API. It only allows executions started by that key to receive project variables in the worker process.

This is useful when a CI key runs a saved Playwright job that needs `HAPPY_PATH_QUEUE_API_KEY`, `TARGET_TENANT`, or other project-specific values.

Presets that can create arbitrary runs, such as `ingest-runner` and `queue-worker`, do not include `variables:use` by default. Add it manually only when that runner must receive project secrets.

## Rotation strategy

Rotate keys instead of deleting and recreating them when you need a zero-downtime rollout.

1. Create or rotate the key from the API keys page.
2. Store the replacement value in your secret manager or CI variables.
3. Roll it out to every worker, pipeline, or MCP host.
4. Verify new traffic, then let the old value expire or revoke it.

## API reference

The API Reference page documents exact endpoint paths, auth modes, request bodies, and response shapes. Use it when implementing an integration after deciding the key and scopes.

Open [API Reference](/docs/api).