When should I use RBAC versus ABAC?

RBAC (Role-Based Access Control) works when your permission model maps cleanly to job functions. Most B2B SaaS products with under 10 roles should use RBAC. ABAC (Attribute-Based Access Control) adds conditions based on resource attributes (e.g., "can edit tasks where status is 'draft' and department is 'engineering'"). Use ABAC when you need fine-grained, dynamic rules that vary by resource properties. Many products start with RBAC and add ABAC-like rules later for specific enterprise requirements. See the [glossary entry on authorization](/glossary/prioritization) for more background.

How do I handle permissions for features that do not exist yet?

Define a permission naming convention (e.g., `resource:action`) and reserve namespace for future features. When a new feature ships, add new permissions to existing roles with sensible defaults. For example, if you add a "Reports" feature, add `reports:read` to all roles and `reports:create` to Admin and Member roles. Communicate the new permissions in your changelog so admins can adjust.

Should I enforce permissions in the UI, the API, or both?

Both, but the API is the authoritative enforcement point. The UI should hide or disable elements the user cannot access (better UX), but never rely on the UI alone because API endpoints can be called directly. Every API endpoint must check permissions independently. This is non-negotiable for security. The [Feature Specification Template](/templates/feature-spec-template) includes a section for documenting API-level authorization requirements.

How do I migrate from a simple admin/member model to a full RBAC system?

Map your existing admin users to the Org Admin role and existing members to the Member role. Ship the new role system with these defaults so no user's access changes on day one. Then gradually introduce new roles (Viewer, Guest, Team Lead) as optional upgrades. Avoid breaking existing workflows by ensuring that the Member role retains all permissions that members had before the migration. ---

Permissions and Role System Specification

What This Template Is For

Every multi-user product needs an authorization model. Who can see what? Who can edit what? Who can invite, remove, or manage other users? These questions seem straightforward until you encounter nested teams, project-level overrides, external collaborators, and API key scoping.

A permissions specification defines the roles, permissions, resource scoping rules, and inheritance logic that govern access throughout your product. Writing it down prevents the two most common failure modes: over-permissive defaults (everyone can see everything, violating least-privilege) and ad hoc permission checks scattered across the codebase (leading to inconsistent enforcement and security gaps).

This template covers role definitions, permission matrices, resource scoping, role hierarchy and inheritance, custom role support, and audit logging. It applies to any SaaS product with team or organizational accounts.

Use this alongside the PRD Template when permissions are part of a larger product initiative. For the technical implementation details (middleware, database schema, caching), pair with the Feature Specification Template. For guidance on how access control fits into product strategy for enterprise customers, see the Product Strategy Handbook.

Evaluate the priority of a permissions overhaul with the RICE Calculator.

How to Use This Template

Start with your organizational hierarchy. Map the entities: organization, team, project, workspace. The hierarchy determines how permissions are scoped and inherited.
Define roles before permissions. Roles represent job functions (Admin, Editor, Viewer). Permissions represent granular actions (create:project, delete:user). Roles bundle permissions into manageable groups.
Build the permission matrix. List every resource type on one axis and every action on the other. Fill in which roles have access. This is the canonical reference for enforcement.
Define inheritance rules. If a user is an Admin at the organization level, what permissions do they have at the project level? Explicit inheritance rules prevent confusion.
Specify what gets logged. Every permission check failure, role change, and sensitive action should produce an audit log entry.
Review with engineering (for enforcement feasibility), security (for threat model alignment), and customer success (for the enterprise customers who will configure these roles).

The Template

Permissions System Overview

Field	Details
Project Name	[Name]
Author	[PM name]
Engineering Lead	[Name]
Security Reviewer	[Name]
Target Release	[Date or milestone]
Status	Draft / In Review / Approved

Summary. [1-2 sentences: what the permissions system covers and the authorization model (RBAC, ABAC, or hybrid).]

Authorization Model. [RBAC (Role-Based Access Control) / ABAC (Attribute-Based Access Control) / Hybrid]

Design Principles.

☐ Least privilege: users get the minimum permissions needed for their role
☐ Deny by default: if no explicit permission is granted, access is denied
☐ Consistent enforcement: permissions are checked at the API layer, not just the UI
☐ Auditable: every permission change and access denial is logged
☐ Manageable: admins can understand and configure permissions without a manual

Organizational Hierarchy

Organization (top-level account)
├── Team / Department
│   ├── Project / Workspace
│   │   ├── Resource (task, document, etc.)
│   │   └── Resource
│   └── Project / Workspace
└── Team / Department

Entity	Description	Who Creates	Permissions Scope
Organization	Top-level account	Account signup	Org-wide settings, billing, user management
Team	Group of users	Org Admin	Team membership, team-level projects
Project	Work container	Team Admin or Member	Project resources, project members
Resource	Individual object	Project Member	CRUD on the specific object

Role Definitions

Role	Scope	Description	Assignable By
Owner	Organization	Full access. Can delete the organization. One per org.	System (at signup)
Org Admin	Organization	Full access except org deletion. Manages billing and users.	Owner
Team Admin	Team	Manages team membership and team settings. Full access to team projects.	Org Admin
Member	Team/Project	Standard access. Creates and edits resources in assigned projects.	Team Admin or Org Admin
Viewer	Team/Project	Read-only access. Cannot create or modify resources.	Team Admin or Org Admin
Guest	Project	Limited access to specific projects. External collaborators.	Team Admin (with Org Admin approval)

Permission Matrix

Legend. C = Create, R = Read, U = Update, D = Delete, M = Manage (configure settings)

Resource	Action	Owner	Org Admin	Team Admin	Member	Viewer	Guest
Organization	M (settings)	Yes	Yes	No	No	No	No
Organization	D (delete)	Yes	No	No	No	No	No
Billing	R	Yes	Yes	No	No	No	No
Billing	U	Yes	Yes	No	No	No	No
Users	C (invite)	Yes	Yes	Team scope	No	No	No
Users	R (list)	Yes	Yes	Team scope	Team scope	Team scope	No
Users	U (role change)	Yes	Yes	Team scope	No	No	No
Users	D (remove)	Yes	Yes	Team scope	No	No	No
Team	C	Yes	Yes	No	No	No	No
Team	R	Yes	Yes	Own team	Own team	Own team	No
Team	U	Yes	Yes	Own team	No	No	No
Team	D	Yes	Yes	No	No	No	No
Project	C	Yes	Yes	Yes	Yes	No	No
Project	R	Yes	Yes	Team scope	Assigned	Assigned	Assigned
Project	U	Yes	Yes	Team scope	If owner	No	No
Project	D	Yes	Yes	If owner	If owner	No	No
Resource	C	Yes	Yes	Yes	Yes	No	No
Resource	R	Yes	Yes	Team scope	Project scope	Project scope	Project scope
Resource	U	Yes	Yes	Team scope	Project scope	No	No
Resource	D	Yes	Yes	Team scope	If owner	No	No

Inheritance Rules

Rule	Behavior
Downward inheritance	Org Admin permissions apply to all teams and projects within the org
Team scope	Team Admin permissions apply to all projects owned by that team
Project override	A user can be given a higher role on a specific project than their team role
No upward inheritance	Project-level permissions do not grant team or org permissions
Guest containment	Guest permissions never inherit beyond the specific project(s) they are invited to

Conflict resolution. When a user has multiple roles (e.g., Member at team level, Viewer on a specific project), the higher permission wins. If an explicit deny is set at any level, it overrides all grants (deny takes precedence).

Custom Roles (if supported)

Feature	Details
Available on	[Enterprise plan only / All plans]
Max custom roles per org	[Limit]
Base template	Custom roles clone an existing role and modify permissions
Restrictions	Custom roles cannot exceed Owner or Org Admin permissions

Custom Role Creation Flow.

Org Admin navigates to Settings > Roles
Clicks "Create Custom Role"
Selects a base role to clone
Toggles individual permissions on/off
Names the role and adds a description
Assigns the role to users

API Authorization

Mechanism	Description
API key scoping	API keys inherit the permissions of the user who created them
OAuth scopes	[List scopes: e.g., read:projects, write:tasks, admin:users]
Service accounts	Non-human accounts with specific roles for automation and integrations
Token permissions	Tokens can be restricted to a subset of the creating user's permissions

Authorization check flow.

Request arrives with authentication token
Identify the user and their roles (cached, refreshed every [X] minutes)
Determine the target resource and action
Check the permission matrix: does any of the user's roles grant this action on this resource?
If no grant found, return 403 Forbidden with error code INSUFFICIENT_PERMISSIONS
Log the check (success or failure) to the audit trail

Audit Logging

Event	Logged Fields	Retention
Role assigned	actor, target_user, role, scope, timestamp	[X] months
Role removed	actor, target_user, role, scope, timestamp	[X] months
Permission denied	user, resource, action, timestamp, IP	[X] months
User invited	actor, email, role, timestamp	[X] months
User removed	actor, target_user, timestamp	[X] months
Custom role created/modified	actor, role_name, permissions_changed, timestamp	[X] months
Sensitive action	actor, action, resource, timestamp, IP	[X] months

Sensitive actions (always logged regardless of success/failure):

☐ Billing changes
☐ Organization settings changes
☐ Bulk user operations
☐ Data export requests
☐ API key creation or revocation

Open Questions

#	Question	Owner	Status	Decision
1	[Question]	[Name]	Open
2	[Question]	[Name]	Open

Filled Example: TaskFlow RBAC System

Role Definitions

Role	Scope	Users (current)	Key Permissions
Owner	Organization	1 per org	All permissions. Transfer ownership. Delete org.
Admin	Organization	~2 per org	User management, billing, all team/project access
Team Lead	Team	~1 per team	Team membership, project creation, team settings
Member	Team	~8 per team	Create/edit tasks and projects within assigned teams
Viewer	Project	~3 per project	Read-only. Can comment but not edit tasks
Client	Project	~1 per project	Read-only on specific project. No team visibility

Inheritance. Admin permissions cascade to all teams and projects. Team Lead permissions cascade to all projects in their team. A Member promoted to Viewer on another team's project gets read-only access to that project without gaining any other team permissions.

Key Takeaways

Define your organizational hierarchy before designing roles and permissions
Build the full permission matrix covering every resource type and action
Enforce permissions at the API layer, not just the UI
Log every permission change and access denial for audit compliance
Start with RBAC and add ABAC-like rules only when enterprise customers require them

About This Template

Created by: Tim Adair

Last Updated: 3/5/2026

Version: 1.0.0

License: Free for personal and commercial use

Permissions and Role System Specification Template