Sharing and Permissions Model Spec Template

RBAC (Role-Based Access Control) assigns permissions through roles: a user is an "Editor" and editors can edit. It is simple to understand and implement. ABAC (Attribute-Based Access Control) evaluates permissions based on attributes of the user, resource, and context (e.g., "users in the engineering department can edit documents tagged 'engineering' during business hours"). It is flexible but complex. ReBAC (Relationship-Based Access Control) defines permissions through relationships (e.g., "the document creator can edit; members of the creator's team can view"). Google Zanzibar popularized this model. For most SaaS products, start with RBAC and extend to ReBAC if you need fine-grained, relationship-driven permissions.

For products with simple RBAC (under 5 roles, no inheritance), building your own with middleware checks is reasonable. For products with complex hierarchies, inheritance, resource-level overrides, or multi-tenancy, use an authorization service. These services handle the hard problems: policy evaluation performance, consistent enforcement across services, and audit logging. The engineering time saved on edge cases and security reviews typically justifies the cost within the first quarter.

Centralize permission evaluation in a dedicated authorization service. Each microservice calls the auth service with (user, action, resource) and gets a boolean response. Do not embed permission logic in individual services. That leads to inconsistent enforcement and security gaps. Cache permission decisions at the API gateway or service mesh level with short TTLs (30-60 seconds) to minimize latency. Invalidate caches when permissions change.

Start coarse and add granularity based on customer feedback. V1: workspace-level roles only. V2: add project-level roles. V3: add object-level overrides if customers request them. Each level of granularity adds UI complexity (more dialogs, more settings), API complexity (more checks per request), and cognitive load (users confused about which level controls what). Only add granularity when customers cannot achieve their access patterns with the current model.

When a user's permissions are downgraded during an active session (e.g., removed from Editor to Viewer while editing a document), immediately switch them to read-only mode. Preserve any unsaved edits locally so the user can copy them. Show a clear notification explaining the change. Do not silently prevent saves, and do not discard in-progress work. For live collaborative sessions, see the [collaboration feature template](/templates/collaboration-feature-template) for real-time permission change handling. ---