RBAC Patterns for SaaS: From Simple Roles to Org-Scoped Permissions
A practical guide to implementing role-based access control in multi-tenant SaaS applications, from basic roles to complex permission hierarchies.
Role-based access control (RBAC) sounds simple: assign roles to users, check roles before allowing actions. But in a multi-tenant SaaS application, the complexity grows quickly. Here's how to think about RBAC as your application scales.
Level 1: Simple Roles
Most applications start here. You have a few built-in roles — typically admin, user, and viewer — and you check them with simple conditionals:
if (user.role === "admin") {
// allow the action
}This works great for single-tenant applications with a small team. Calimatic Identity ships with three built-in roles that cover this pattern out of the box.
Level 2: Permission-Based Access
As your feature set grows, role checks become brittle. An admin can do everything, a user can do most things, and a viewer can read — but what about the support agent who needs to view user details but not modify billing?
The solution is to decouple roles from permissions. Each role gets a set of permissions, and your code checks permissions instead of roles:
if (user.permissions.includes("users:read")) {
// allow the action
}Now you can create a "Support" role with users:read and tickets:manage permissions without granting full admin access. In Calimatic Identity, you define custom roles in the admin panel and assign any combination of permissions to them.
Level 3: Role Hierarchy
Permission lists get long. When you have 50 permissions and 10 roles, managing the matrix becomes tedious. Role hierarchy solves this by allowing roles to inherit permissions from parent roles:
super_admin → admin → user → viewerA super_admin automatically inherits all permissions from admin, which inherits from user, which inherits from viewer. You only need to specify the additional permissions at each level.
Calimatic Identity supports role hierarchy natively. Set a parent role in the role editor, and inheritance is handled automatically.
Level 4: Org-Scoped Roles
This is where multi-tenancy changes everything. In a multi-tenant application, a user might be an admin in Organization A but just a viewer in Organization B. Global roles don't work here — you need org-scoped role assignments.
Calimatic Identity handles this at the platform level. When you assign a role to a user, you specify the organization scope. Our API enforces this automatically:
GET /api/v1/organizations/{orgId}/usersreturns only users in that org- Permission checks are always scoped to the user's role within the current organization
- A user's role in Org A has zero bearing on their access in Org B
Level 5: Resource-Level Permissions
The most granular level ties permissions to specific resources. "User X can edit Project Y but only read Project Z." This is typically implemented with an access control list (ACL) on top of RBAC.
For most SaaS applications, org-scoped RBAC (Level 4) is the sweet spot. It provides strong isolation and flexible access control without the complexity of per-resource ACLs.
Choosing the Right Level
- Internal tool or MVP: Level 1 (simple roles) is fine
- Growing SaaS product: Level 2-3 (permissions + hierarchy) covers most needs
- Multi-tenant platform: Level 4 (org-scoped roles) is essential
- Document/project management: Level 5 (resource-level) may be needed
Start at the level you need today, and Calimatic Identity scales with you. Our platform supports all five levels, so you can progressively add complexity without re-architecting your auth system.