Service Accounts

Workspace service accounts are machine principals for non-interactive Breyta
work.

Quick Answer

Use service accounts when a worker machine should call Breyta without a human
login session.

Human operators manage service accounts with normal interactive auth.
Worker machines authenticate with --api-key or BREYTA_API_KEY.
Jobs workers are the primary bootstrap use case, but the same machine-auth
model can be granted broader API scopes for agent-style automation.

Create A Worker Identity

Create a service account with explicit worker scope and allowed job types:

breyta service-accounts create \
  --name codex-review-worker \
  --scope jobs.worker \
  --job-type codex-review

--scope accepts repeated flags or comma-separated values. --capability
remains accepted as a compatibility alias.

Inspect or update it later:

breyta service-accounts list
breyta service-accounts show <service-account-id>
breyta service-accounts update <service-account-id> --status disabled

Mint And Rotate API Keys

Create a key for that service account:

breyta service-accounts keys create <service-account-id> --name ci-runner

The returned apiKey is shown once. Store it immediately in the worker
environment or your secret manager.

List or revoke keys:

breyta service-accounts keys list <service-account-id>
breyta service-accounts keys revoke <service-account-id> <key-id>

Create A Broader Agent Identity

When an unattended agent needs more than worker duties, add explicit scope
grants for the surfaces it should use:

breyta service-accounts create \
  --name automation-agent \
  --scope flows.read \
  --scope flows.manage \
  --scope flows.run \
  --scope runs.read \
  --scope resources.read \
  --scope resources.write \
  --scope connections.read \
  --scope connections.manage \
  --scope triggers.read \
  --scope triggers.manage

For a read-only workspace MCP client that should discover flows, inspect MCP
interfaces, inventory connections, read step references, read run status, and
report feedback, use a narrower MCP-shaped identity:

breyta service-accounts create \
  --name workspace-mcp-agent \
  --scope flows.read \
  --scope runs.read \
  --scope resources.read \
  --scope installations.read \
  --scope connections.read \
  --scope steps.read \
  --scope feedback.send

Add flows.run only when that MCP client should expose the run toolset or
call flow MCP interfaces through call_flow_tool.
Keep installations.read when the MCP client should discover or call installed
public-flow tools.
Add flows.manage only when that MCP client should create or update draft
flows through create_flow_draft. Use Workspace MCP
for the endpoint config and toolset headers.

For a broad trusted agent, use the catch-all scope over the known
service-account matrix:

breyta service-accounts create \
  --name full-agent \
  --scope workspace.full

Run A Worker With Machine Auth

export BREYTA_API_URL="https://flows.breyta.ai"
export BREYTA_WORKSPACE="ws-acme"
export BREYTA_API_KEY="<service-account-api-key>"

breyta jobs worker run \
  --type codex-review \
  --handler ./scripts/run-review.sh

breyta jobs worker run passes the same auth mode through to helper commands
such as breyta jobs worker progress, attach-file, attach-kv,
attach-table, finish, and fail.

Scope Model

Service accounts belong to one workspace.
Scopes describe what the machine may do.
The command surface and selected direct REST routes are authorized by an
explicit scope matrix.
workspace.full grants the full known service-account matrix for that
workspace, but it does not bypass user-only or unknown surfaces.
*.manage implies *.read within the same domain.
resources.write implies resources.read.
jobs.worker is separate from jobs.manage; claiming and updating leased
jobs stays distinct from creating and inspecting jobs.
Allowed job types narrow worker and job-creation operations that target one
job type.
API keys are stored hashed and can be revoked independently.

Scope Families

Common scope families:

jobs.worker, jobs.read, jobs.manage
flows.read, flows.manage, flows.run
runs.read, runs.manage
resources.read, resources.write
connections.read, connections.manage
profiles.read, profiles.manage
installations.read, installations.manage
triggers.read, triggers.manage
waits.read, waits.manage
secrets.read, secrets.manage
flow-health.read, flow-health.manage
apps.read, apps.manage
steps.read, steps.manage
billing.read, billing.manage
feedback.send
workspace.full

This matrix is intentionally explicit and fail-closed. New product surfaces stay
denied to service accounts until they are added to the matrix.

Direct HTTP interface routes use the same split: starting an author or
installation interface requires flows.run; polling an interface statusUrl
can use runs.read.

User-Only Surface

Service accounts do not manage their own identity plane.

Creating, updating, listing, or revoking service accounts and their keys
remains an operator action under human auth.
Auth/session routes and browser-oriented UI routes are outside the
service-account matrix.

Recommended Split

Use human auth for operator/admin flows such as creating service accounts,
inspecting workspace setup, or editing flows.
Use service-account API keys for unattended workers and agents, with the
smallest scope set that matches the automation.