Workspace roles and authorization

Workspace Roles & Authorization

When to Use

Use when designing or auditing role-based (RBAC) or attribute/resource-based (ABAC) access control inside multi-tenant workspaces.

Four Orthogonal Authorization Planes

Never conflate these four distinct concepts into a single role check:

1. Platform / Global Identity Role: Whether the actor is a normal SaaS user or an internal platform operator (e.g., platform_support via explicit audited break-glass flow). A global admin flag should never silently bypass normal workspace UI boundaries without explicit elevation.
2. Workspace Membership Role: The user's role within the active workspace (owner, admin, member, billing, viewer, guest), stored on workspace_memberships(workspace_id, user_id, role).
3. Resource-Level Scope / Ownership: Fine-grained access within a workspace (e.g., private project membership, creator of a comment, guest restricted to a single channel/folder, or scoped API key permissions).
4. Workspace Plan Entitlement: Whether the workspace's subscription includes a capability (sso_enabled, custom_roles, max_projects). Even a workspace owner cannot use a feature the workspace's plan does not entitle, and a viewer cannot mutate settings even on an Enterprise plan!

Server-Side Policy Enforcement Rules

1. Evaluate (Actor, Membership, Action, TargetResource) Together

Every protected operation must evaluate:

authorize({
  actor,               // Authenticated user or API key principal
  membership,          // Verified active membership in target workspace
  action: 'project.delete',
  resource: project,   // Loaded from DB with resource.workspaceId === membership.workspaceId
});

• Never check only membership.role === 'admin' while loading Project.findById(req.params.id) without verifying project.workspaceId === membership.workspaceId!
• For child resources (task $\rightarrow$ project $\rightarrow$ workspace), verify that the entire parent chain belongs to the same workspace.

2. Explicit Permission Capabilities Over Scattered Role Strings

• Map roles (owner, admin, member, viewer) to explicit capability permissions (workspace:delete, members:invite, members:remove, billing:manage, project:create, project:write, project:read).
• Enforce role hierarchy invariants on member management:
  • An admin cannot remove an owner, promote themselves or anyone else to owner, or modify an owner's role.
  • A member cannot grant a role or API-key scope higher than the permissions they currently hold (privilege escalation prevention).

3. Scoped Workspace API Keys & Service Accounts

• Bind workspace API keys and incoming webhooks explicitly to a single workspace_id with an explicit permission scope (read:projects, write:tasks) and expiration/revocation support.
• Never issue a user-global API key that implicitly grants access to every workspace the user joins in the future unless explicitly scoped and consented per workspace.

4. Honest Error Semantics (403 vs. 404 vs. Empty List)

• For resources belonging to another workspace, return 404 Not Found so cross-tenant resource IDs cannot be enumerated.
• Within the same workspace, when an authenticated viewer attempts an unauthorized mutation (POST/DELETE), return an explicit 403 Forbidden with a clear domain error—never silently return 200 OK or an empty array that misleads the UI into thinking the action succeeded or data was deleted.