Workflow Permissions#

Workflow permissions restrict which users or roles can execute a given workflow. They are defined per-workflow in YAML, evaluated server-side on every run request, and reflected in the frontend via a canRun boolean to gate UI actions.

YAML Definition#

Add a top-level permissions list to a workflow definition. Each entry is either a role name or a user email address (case-insensitive):

workflow:
  id: my-restricted-workflow
  permissions:
    - admin
    - sarah.smith@example.com

See the full example in examples/workflows/permissions_example.yml. Omitting permissions (or leaving it empty) allows any authenticated user to run the workflow.

Backend Enforcement#

Permission check logic lives in Workflow.check_run_permissions():

• If workflow_permissions is empty → allow (open to all).
• If the caller's role is admin → allow unconditionally.
• Otherwise, check whether the caller's email or role appears in the lowercased, stripped permissions list. If neither matches → deny.

The Roles enum (keep/identitymanager/rbac.py) defines available roles: admin, noc, webhook, and workflowrunner 1.

Enforcement happens in two places:

1. POST /{workflow_id}/run — The run endpoint calls check_run_permissions() against the loaded Workflow object's workflow_permissions. On failure it raises HTTP 403: "Insufficient permissions to execute this workflow" 2.

2. POST /workflows/query — For each workflow returned by the list endpoint, the raw YAML is parsed, permissions extracted, and check_run_permissions() called with the requesting user's email and role. The result is set as the canRun field on the WorkflowDTO 3. This means the list API tells the frontend ahead of time whether a workflow is executable by the current user.

Frontend Surfacing#

The Workflow TypeScript type carries canRun?: boolean from the API response.

In ManualRunWorkflowModal, after fetching workflows via useWorkflowsV2, the list is immediately filtered:

const filteredWorkflows = workflows?.filter((w) => w.canRun);

If any workflows were removed by this filter (i.e., filteredWorkflows.length !== workflows?.length), a yellow callout is shown: "Some workflows are not visible to you because you lack permissions" 4. Workflows with canRun: false never appear in the run selector.

Flow Summary#

Key Files#