Description
Custom Permission Roles let workspace administrators translate operating responsibilities into reusable permission bundles. The role builder presents the platform-defined permission catalog in ordered, labeled groups, while the server validates every submitted atom against that same source. Administrators can create, rename, update, and retire custom roles, then assign them to human or agent principals through the Access management surface.
Roles participate in Dots’ additive authorization algebra: a principal receives the union of assigned role permissions and any applicable Dotabase grants. System roles remain immutable, owner-reserved permissions cannot be smuggled into custom roles, and the final active human Owner is protected by service invariants. The result is flexibility for real team structures without turning access policy into an opaque rules engine.
Selling Points
- Models responsibilities such as content steward, automation operator, or reviewer as named bundles that can be reused across a team.
- Keeps human-readable labels and descriptions synchronized with the enforced permission catalog, preventing configuration drift.
- Protects high-risk owner capabilities even when an administrator edits a custom role.
- Makes role changes auditable and immediately effective for subsequent authorization checks.
- Gives administrators a visual builder while retaining API-backed validation at every write boundary.
User Story
A security administrator creates a “Content Steward” role, enables schema and row-management permissions, and leaves member administration disabled. They assign the role to two teammates and an agent that maintains structured content. Each principal gains the intended capabilities without receiving Owner or Admin, and the administrator walks away with one reusable role they can adjust as responsibilities evolve.
Extension Surface
This capability is configurable. Administrators change role names and permission membership through the shipped UI in apps/web/src/modules/access/management/RoleBuilderPanel.tsx and the API backed by packages/access/src/service.ts; no source edit is required. packages/access/src/groups.ts defines the fixed presentation grouping, so callers configure bundles from supported atoms rather than registering new permission semantics.
Capabilities & Limits
- Creates and updates company-scoped custom roles from validated permission atoms.
- Assigns reusable roles to both human and agent principals.
- Prevents mutation of system roles and inclusion of owner-reserved atoms in custom roles.
- Uses additive allows only; a custom role cannot override another grant with a deny.
- New permission atoms require a platform code change and enforcement census update.
Implementation Map
packages/access/src/groups.tspackages/access/src/service.tspackages/db/src/schema/access-roles.tsapps/web/src/modules/access/management/RoleBuilderPanel.tsx