API Keys

API keys authenticate as Bearer tokens and are scoped to one organization.

Release-day auth concepts are:

• accessToken
• apiKey

Public docs cover how API keys work on public routes. They do not treat key-management routes as part of the public route reference.

Public usage

Prompt Orchestra uses route-scoped API keys. The shipped model is narrower than a generic read / write / execute story.

Common public scopes include:

• agents:read
• agents:write
• runs:read
• models:read
• skills:read
• skills:write
• tools:read
• tools:write
• evaluations:read
• evaluations:write

resolveAuthorizedPrincipal(...) enforces org binding plus the required API-key scope for each route.

Presets

Prompt Orchestra currently ships three preset-backed API-key shapes:

• runtime_default
  • Scopes: agents:read, runs:read
  • Intended use: setup verification plus stable backend read and inspection flows
  • Not for: public execution routes, legacy v1 run compatibility routes, or non-public prompt/cost/session/realtime surfaces
• runtime_execution
  • Scopes: skills:read, runs:read, runs:write
  • Intended use: trusted backend public skill execution, generated-image jobs, and run-detail inspection
  • Not for: interactive user execution, stateless authoring/apply workflows, or non-public prompt/cost/session/realtime surfaces
• authoring_ci
  • Expiry required
  • Scopes: agents:read, agents:write, models:read, skills:read, skills:write, tools:read, tools:write, evaluations:read, evaluations:write, runs:read
  • Intended use: stateless CI/apply authoring for agents, skills, tools, and evaluations plus run inspection
  • Not for: public execution routes or interactive user execution

Machine authoring is the shipped authoring_ci preset, not a free-form "all automation" key. Backend execution uses runtime_execution, not authoring_ci.

Setup and admin routes

The shipped product uses /api/settings/api-keys* for setup and admin flows. Those routes require a user access token plus org settings permissions and are outside the public route reference. Listing keys or presets needs settings.read; create, rotate, and revoke need settings.update.

Treat them as setup/admin surfaces, not as part of the supported public route catalog.

See also

• API Key Presets
• Which Routes Support Which Auth
• Public Boundary