Files
windmill/docs/workspace-roles.md
T
e24a4309d0 fix: resolve the caller's role capabilities at authentication (#12501)
* fix: resolve the caller's role capabilities at authentication

* chore: update ee-repo-ref to e4bfe4229dfd07f6c356835c2ac0e80c2729d582

This commit updates the EE repository reference after PR #990 was merged in windmill-ee-private.

Previous ee-repo-ref: 637d417668a1c3b4203cfedf782bd72648fdb102

New ee-repo-ref: e4bfe4229dfd07f6c356835c2ac0e80c2729d582

Automated by sync-ee-ref workflow.

---------

Co-authored-by: windmill-internal-app[bot] <windmill-internal-app[bot]@users.noreply.github.com>
Co-authored-by: Ruben Fiszel <ruben@windmill.dev>
2026-11-18 23:21:44 +01:00

8.8 KiB

Workspace roles

What a non-admin member may author, manage and see is its role. developer and operator are the default roles; a licensed EE instance defines its own list in the workspace_roles global setting (at least one role), and any workspace may override a role's capabilities in workspace_settings.role_overrides, or, when licensed, add roles of its own there. A lapsed license freezes them rather than dropping them (custom_roles_enabled): the stored list and the workspace-only roles keep applying, writes that change them are refused, and resetting the list to the defaults or removing a workspace-only role stays open. Falling back to the defaults instead would hand a restricted developer everything. Workspace admin is not a role: it is the is_admin flag on top of whichever role a member holds, and holds everything. The code is windmill_common::roles.

Capabilities

Capability Values Enforced
code bool yes: scripts, previews, dependency jobs, dynamic selects, resolving jobs, data table migrations, eval datasets
flows none / compose / full yes; also AI agents, whose tools are checked as composed steps
apps none / compose / full yes; low-code apps and worker-built apps need full
manage_schedules, manage_triggers bool yes, see docs/operator-write-rights.md
run bool yes, see Runs
fork bool yes, at both fork routes; unset by every layer, it is granted exactly to an unrestricted role
visibility.* bool per page no, UI only

compose is the former operator builder right: the composition-only checks of docs/operator-builder-rights.md run for it and are skipped only at full. full flows or apps without code is refused at write, since both carry inline code.

Stored values are patches: an unset key falls through to the layer below, so a key added later reads as "never configured". The layers, top first: the workspace override, the instance definition, then RoleCapabilities::base_for (FULL for developer, the legacy operator for any other name). A role name no longer defined resolves to NONE, so deleting a role fails closed; deleting one that a member, invite, auto-invite or instance group mapping still names is refused, and so is deleting an instance role that a workspace still overrides (the override would fall onto base_for instead of the definition it was written against).

Runs

run withdrawn makes a role view-only: its members see what folder and item rights grant, runs, logs and results included, and start nothing. gate_role_runs sits on the jobs router and refuses every path under run/, run_wait_result/, run_and_stream/, run_inline/, restart/ and add_batch_jobs/ (GET included, which starts runs there), so a run route added under those prefixes is gated for free. It lets through the dependency-lock and dynamic-select routes, which code gates, and run/workflow_as_code, a step of a run already started. The three script preview routes (run/preview, run_inline/preview, run_wait_result/preview) check run in their handlers instead, after the exemption that lets a running job's SDK send a data table query there, since jobs a view-only member owns still run as them. Callers that push without the router check check_role_can_run themselves: the MCP per-runnable tools (which tools/list also omits for such a role, along with the run endpoint tools), eval experiment runs and members-only Slack agent shares (which run as the asking member). An MCP session token and the in-app AI session hold such a member to read-only, so neither offers a run tool. Resuming or approving a suspended step is not a run. Schedules and triggers keep their own rights, apps run their runnables on the app's policy and are not gated, and a job started by a schedule or trigger acts as its owner, so from inside it a view-only owner cannot start further runs through the API either.

Unlike fork, withdrawing run makes a role restricted: it is an enforced gate on hot routes, and the fast path is what spares every unrestricted caller a role lookup on each run. It does not change seats: a role is a full seat by what it authors, not by whether it runs.

Forks

A member's role carries into a fork: the forker, and every member copy_members or add_admins_and_developers_to_forks brings, joins the fork with the role they hold in the parent, and the fork gets the parent's role_overrides so the name means the same there. A protection ruleset's fork_role_mapping ({ role here: role in the fork }) replaces that role; where several rulesets map one role, the first by name wins. A role named by a mapping cannot be deleted. A fork's non-admin creator may add a parent member only when the mapping makes them a developer, so re-adding cannot undo a mapping that restricts.

fork, like visibility, does not make a role restricted: withdrawing it from developer must not turn every developer into an operator for the raw is_operator checks. So the fork routes read it from the member's role (caller_can_fork), never through caller_capabilities' fast path.

Who is restricted

ApiAuthed::is_operator means "this member's role is restricted", computed at authentication from the role, never from usr.operator alone. Every gate fast-paths on it (caller_capabilities returns FULL for an unrestricted or admin caller without reading the role), so it must stay derived from the role: a stale flag lets a restricted member through. The authentication cache holds it for up to 120s.

ApiAuthed::capabilities is the role itself, read for each request before its handler runs, so a capability check inside a save's transaction, the Hub rule included, never needs a second connection. It is read from the role caches and never stored with the cached login: storing it there would need every role change to clear the login on every server, running jobs' tokens included. An identity built outside a request has none, and caller_capabilities reads the role.

usr.operator is kept as "this role cannot write code", which is what clients that predate roles read it as. A member's role is usr.workspace_role, or, while that is NULL, operator / developer from usr.operator: rows written by paths that know nothing of roles stay meaningful. The old usr.role column is unrelated and holds legacy display strings.

Seats

A role that writes or composes anything costs a full seat; anything else half. Billing SQL cannot merge capability patches, so role_seat materializes the author flag per role (workspace_id = '' for the instance, a row per workspace override), rewritten by sync_role_seats after every write to either setting. Every count reads it through AUTHOR_SEAT_SQL, and usage telemetry reports builders (authors anywhere) against non-builders the same way. A change that adds seats under an offline license is priced inside the transaction that writes it, by check_seat_cap_for_role_change.

Legacy operator_settings

/operator_settings still works: it is applied as an override of the operator role, dropping any key equal to what the instance gives that role, and the payload is mirrored into the operator_settings column for git sync and older servers. The migration moved every key a workspace had changed from its default into role_overrides.operator the same way. The workspace list still returns an operator_settings object for a restricted member, synthesized from its role, alongside role and capabilities.

In the settings document

role_overrides in the settings document (export settings.json, settings.yaml, git sync) is the stored map, except that the entry of a role the instance does not define carries workspace_only: true. The stored map cannot tell an override of instance role X from adding role X, and the target of a promotion may lack X. So the apply refuses the whole document, dry run included, before writing anything, if:

  • an unmarked entry names a role the target instance does not define, unless the target workspace already has it as a workspace-only role (a file pulled before the marker existed), or
  • a marked entry names a role the target instance defines.

The marker is never stored. Roles are written before every other setting, so an instance group mapping in the same file can name a role it adds. A workspace-only role the file removes is kept until a final write, after whatever named it has been rewritten, so the in-use check passes.

The document's operator_settings is derived from the effective operator role, not read from the column: only the legacy endpoint rewrites the column, so after a role edit it holds stale flags. A document that states role_overrides never applies operator_settings, and warns when it was edited to disagree with the operator role. A document without role_overrides (pulled before roles existed) applies it as before, diffed against the column.