Roles and permissions
Workspace roles, ranked permissions, invitation limits, and organization fan-out.
Every workspace membership has exactly one role: Viewer, Member, Admin, or Owner. Roles are rank-based: a higher role includes the permissions of the ones below it.
Role matrix
Enterprise environment checks use this rank (enterpriseRoleCan / workspaceRoleCan):
| Role | Rank | read | execute | write | promote | manage-secrets |
|---|---|---|---|---|---|---|
| Viewer | 0 | Yes | No | No | No | No |
| Member | 1 | Yes | Yes | No | No | No |
| Admin | 2 | Yes | Yes | Yes | Yes | No |
| Owner | 3 | Yes | Yes | Yes | Yes | Yes |
write and promote share rank 2. manage-secrets is Owner-only.
Typical product gates that use the same ranks:
| Action | Minimum role |
|---|---|
| Read workspace resources, list members, GET git repository, GET agent rollout | Membership (any role) |
Run workflows (execute) | Member |
Invite via session POST /api/workspace-members or v1 members | Admin |
Create or revoke API keys (session /api/api-keys) | Admin |
| PATCH/DELETE git review repository | Admin |
| PATCH agent-runtime rollout | Admin |
| Configure enterprise SSO (plus org owner/admin) | Admin |
| Prepare, publish, promote or stop a workflow destination | Member with write and execution access; publication also requires exact AIMS approval |
| Execute a single deployed step with real effects | Admin or Owner with execution access and recent MFA |
| Manage external secret providers | Owner (manage-secrets) |
| Observability retention POST | Owner |
Checks compare the actor's role rank to the minimum allowed role. Passing ["Admin", "Owner"]
means Admin or higher.
Approvals in the main navigation uses effective AIMS assignments. A workspace Owner is not automatically an AIMS System Owner, Manager or Reviewer. Organization Owners may configure the organization approval policy; the independent and Owner-authorized paths retain their assignment and separation rules. Viewers can inspect permitted workflow metadata but cannot edit, simulate, publish or operate destination switches. See AI governance.
How you become Owner
Invite APIs reject owner. Stored invite roles are admin | member | viewer.
You become Owner only when:
- Platform bootstrap writes org + workspace membership
owner(FLUXUS_BOOTSTRAP_OWNER_*). - Google provisioning creates your personal org/workspace as
owner. - An organization-level role of
owneris synced onto workspaces (normalizeWorkspaceMembershipRolekeepsowneron that path).
Creating a workspace yourself makes you Admin, not Owner.
Organization membership created by a workspace invite is member (or unchanged if you already
had a stronger org role). A workspace admin invite does not promote you to org admin.
Invitation permission split
The same inviteWorkspaceMember helper is used everywhere; authorization differs:
- tRPC
workspaceShell.workspaceMembers.invite: any workspace member. - Session and v1: Admin or Owner (v1 also needs a workspace-scoped API key).
Unknown invite roles do not silently become Viewer at the HTTP/tRPC boundary. They throw
Member role must be admin, member, or viewer. Viewer is the fallback only inside
normalizeWorkspaceMembershipRole (org fan-out and Google invite accept).
Scope boundaries
- Workspace: isolation unit for resources, members, and API keys.
- Organization: billing/identity container; SSO/SCIM; optional projects; membership fan-out.
- API key: always bound to one workspace. The key is valid only while the owning user is not banned and still has both workspace and organization membership.
- Session: may switch among workspaces the user belongs to; cannot act on others (
403).
More structure: Organizations and workspaces. Enterprise gates: Enterprise. Settings map: Workspace settings.