Roles & API Keys

Roles and permissions

Four built-in roles cover the common cases. Each row below is an individually checkable permission verb (the wire string an admin types into roles.yaml); Admin is a catch-all that satisfies any check.

Permission	admin	editor	runner	viewer
flow:read	✓	✓	✓	✓
flow:write	✓	✓
flow:run	✓	✓	✓
run:read	✓	✓	✓	✓
run:delete	✓	✓
run:terminate	✓	✓	✓
environment:read	✓	✓	✓	✓
environment:write	✓	✓
system:read	✓	✓	✓	✓
user:manage	✓
Admin (catch-all)	✓

Roles map to intent: admin (full), editor (flows/envs), runner (run/monitor), viewer (read-only). A custom role can grant flow:run without Admin for a least-privilege automation account. If you don’t know your role, the whoami REST endpoint (or the equivalent MCP tool) returns it.

Upgrading from a release where this role was called invoker

The built-in role is renamed invoker → runner; there is no alias. Roles are stored as plain strings and looked up by name, so any existing reference to invoker — a user or API key assignment, a custom role’s extends: invoker, or a DefaultRoles entry in your provider config — silently resolves to zero permissions after upgrade rather than an error. Update every stored invoker reference to runner in the same maintenance window as the binary upgrade. Affected users and API keys will need to re-authenticate.

API keys for service-to-service

Keys are scoped to a user or a role, can be rotated without service disruption, and are revealed exactly once on creation.

Rotation is a rotate-api-key call: the old key keeps working until you delete-api-key it, so a CI pipeline can pick up the new key on its next run before the old one is revoked. This is the path for wiring monitoring, deployment, and scheduled runs into your installation.

An API key can be user-bound — runs carry an owner_user_id claim, so per-user credential overrides apply to automation as they would to the human.

Audit trail

Every authenticated mutation lands in the audit log: create flow, update environment, set secret, rotate API key, transition staging, promote to production, login attempts (success and failure), API key creation/revocation, role assignment changes. Each entry is a structured Serilog event with:

Timestamp · EventType · UserId · EntityType / EntityId · Outcome · (SourceIp when applicable)

Entries route through the standard Serilog pipeline — same sinks as the rest of platform logging. For compliance retention, ship the audit log to your SIEM (ELK, Loki, Splunk) via the configured sink; the local file sink is for short-term troubleshooting. The log is queryable via /api/v1/platform/logs for ad-hoc investigation.