API keys and scopes
How to choose project API key scopes and safely give machines access to BernOps.
On this page
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; 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.
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.
- Create or rotate the key from the API keys page.
- Store the replacement value in your secret manager or CI variables.
- Roll it out to every worker, pipeline, or MCP host.
- 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.