Permissions and Role System Specification Template

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.

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.

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.

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. ---