RBAC and Permissions Architecture for SaaS

Role-based access control (RBAC) is the foundation of multi-tenant authorization. It determines who can do what within your product — which users can read data, write data, manage other users, and access administrative functions. RBAC implemented correctly is nearly invisible to users. Implemented incorrectly, it produces security incidents (users accessing data they should not see), support tickets (users locked out of features they need), and architectural debt that takes quarters to fix.

This guide covers the core RBAC data model, role hierarchy patterns, attribute-based extensions, enforcement architecture, and multi-tenant isolation.

🗄️ The RBAC Data Model

RBAC at its core is three entities: users, roles, and permissions. Users are assigned roles. Roles are assigned permissions. Users inherit permissions through their roles.

-- Roles table
CREATE TABLE roles (
  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  account_id UUID REFERENCES accounts(id),  -- NULL = system-wide role
  name       TEXT NOT NULL,                  -- 'admin', 'member', 'viewer'
  description TEXT,
  UNIQUE(account_id, name)
);

-- Permissions table (the action catalog)
CREATE TABLE permissions (
  id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  action TEXT NOT NULL UNIQUE  -- 'reports:read', 'members:invite', 'billing:manage'
);

-- Role-permission assignments
CREATE TABLE role_permissions (
  role_id       UUID REFERENCES roles(id) ON DELETE CASCADE,
  permission_id UUID REFERENCES permissions(id) ON DELETE CASCADE,
  PRIMARY KEY(role_id, permission_id)
);

-- User-role assignments (scoped to account for multi-tenancy)
CREATE TABLE user_roles (
  user_id    UUID REFERENCES users(id) ON DELETE CASCADE,
  role_id    UUID REFERENCES roles(id) ON DELETE CASCADE,
  account_id UUID REFERENCES accounts(id),
  PRIMARY KEY(user_id, role_id, account_id)
);

The key design decision: roles are scoped to accounts (account_id on the roles table). A user who is an admin in Account A has no elevated permissions in Account B — even if they are also a member of Account B. This is how multi-tenant isolation works at the authorization layer.

🔑 Roles vs Permissions — The Distinction

Roles are labels (Admin, Member, Viewer). Permissions are specific capabilities (reports:read, members:invite, billing:manage). The role is what you show users. The permission is what you check in code.

Why this distinction matters: If you check roles in code (if (user.role === 'admin')), you couple business logic to role names. When you want to give Members permission to invite users — without making them admins — you must change code in every place you checked the role. If you check permissions instead (if (user.can('members:invite'))), you only change the role-permission assignment in the database.

Permission naming convention: Use resource:action format. Resources map to your data model (reports, members, billing, workspace). Actions are standard verbs (read, write, delete, manage). Keep the permission catalog small — 15–30 permissions covers most SaaS products at seed stage.

🏗️ Role Hierarchy and Default Roles

Most B2B SaaS products need three default roles at seed stage:

Custom roles (where accounts can create their own named roles with specific permission sets) are a seed-to-Series A feature. At pre-seed, the four default roles above cover the vast majority of customer needs. Defer custom roles until enterprise customers request them — the complexity is significant.

🔒 UI Enforcement vs API Enforcement

Authorization must be enforced at the API layer. UI enforcement (hiding buttons from users who lack permissions) is a UX enhancement, not a security control. An API that relies on the UI to hide sensitive actions is not secured — it is obscured.

API enforcement pattern:

// Middleware that checks permissions on every request
async function requirePermission(permission: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const userPermissions = await getUserPermissions(
      req.user.id,
      req.account.id
    );

    if (!userPermissions.includes(permission)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    next();
  };
}

// Applied to routes
router.post(
  '/members/invite',
  requirePermission('members:invite'),
  inviteMemberHandler
);

UI enforcement pattern: After loading the user's permissions server-side, pass a permissions array to the frontend. Gate UI elements based on this array — but never treat the UI check as the security boundary.

Cache the permissions lookup per request session to avoid N database queries per page load. A short-lived cache (5 minutes) is acceptable for permissions data.

🏢 Multi-Tenant Isolation in RBAC

Multi-tenant RBAC has one absolute rule: a user's role in one account must never grant permissions in another account. This isolation must be enforced at the data query level, not just the application level.

Query pattern that enforces tenant isolation:

-- Always scope permission queries to the current account
SELECT DISTINCT p.action
FROM permissions p
JOIN role_permissions rp ON rp.permission_id = p.id
JOIN user_roles ur ON ur.role_id = rp.role_id
WHERE ur.user_id = $1
  AND ur.account_id = $2;  -- Current account scope is non-negotiable

The most common RBAC security bug in multi-tenant SaaS: loading user permissions without scoping to the current account, then trusting that the application logic will filter correctly. It does not — always scope at the query level.

What to Do Next

If you have role checks in code (if (user.role === 'admin')): refactor to permission checks before adding new features. The refactor is a one-time cost that pays off every time you need to change what a role can do. If you are designing RBAC for the first time: implement the four-table model above, define 15–20 permissions using resource:action naming, and enforce at the API layer with a reusable middleware. If you have multi-tenant customers: audit every permission query to confirm it is scoped to account_id. This is your highest-priority security review.