RBAC & Permissions

Runbook access is controlled by three permissions and client-level scoping.

Permissions

Permission	Grants
runbooks:read	View runbooks, versions, action catalog, executions, and step results
runbooks:write	Create, edit, delete runbooks. Manage client access grants.
runbooks:execute	Trigger runbook execution and cancel running executions

These permissions are assigned to roles in Admin > Roles. A user needs the appropriate permission on a role that covers the runbook's client scope.

Risk Tier Authorization

Beyond the base runbooks:execute permission, risk tiers impose additional requirements:

Risk Tier	Who Can Execute
read_only	Any user with runbooks:execute
operational	Any user with runbooks:execute (confirmation required in UI)
destructive	Super admin required (user must have the super-admin flag)

Client Scoping

Runbooks support two access models:

Global Runbooks

A runbook with no client access restrictions is visible to all users who have runbooks:read permission, regardless of their client scope. This is the default for new runbooks.

Per-Client Runbooks

When specific clients are assigned to a runbook (via the Client Access section in the editor), the runbook is only visible to users whose role grants access to at least one of those clients.

The scoping rules:

1. Viewing -- User must have runbooks:read and access to at least one of the runbook's assigned clients (or the runbook must be global).
2. Executing -- User must have runbooks:execute, access to the target host's client, and the runbook must be accessible to that client.
3. Editing -- User must have runbooks:write. Client access grants are managed through the PUT /api/v1/runbooks/{id}/access endpoint.

API Endpoints and Required Permissions

Endpoint	Method	Permission
GET /api/v1/runbooks	GET	runbooks:read
GET /api/v1/runbooks/actions	GET	runbooks:read
POST /api/v1/runbooks	POST	runbooks:write
GET /api/v1/runbooks/{id}	GET	runbooks:read
PUT /api/v1/runbooks/{id}	PUT	runbooks:write
DELETE /api/v1/runbooks/{id}	DELETE	runbooks:write
GET /api/v1/runbooks/{id}/versions	GET	runbooks:read
GET /api/v1/runbooks/{id}/versions/{version}	GET	runbooks:read
GET /api/v1/runbooks/{id}/access	GET	runbooks:read
PUT /api/v1/runbooks/{id}/access	PUT	runbooks:write
POST /api/v1/runbooks/{id}/execute	POST	runbooks:execute
POST /api/v1/runbooks/{id}/preview	POST	runbooks:read
GET /api/v1/runbook-executions	GET	runbooks:read
GET /api/v1/runbook-executions/{id}	GET	runbooks:read
POST /api/v1/runbook-executions/{id}/cancel	POST	runbooks:execute

Service Account Access (MCP)

MCP tools use service account API keys. The service account's role determines runbook access:

• The API key must belong to a service account with a role that includes the relevant runbooks:* permissions.
• Client scope on the service account restricts which runbooks and hosts are accessible.
• Executions triggered via MCP are recorded with trigger_source: ai_chat for audit purposes.