How to create a custom role in the Role Registry
The "New Role" form creates a role with a type, tier, clearance, data scope and explicit allowed and denied permissions.
Have questions or need step-by-step guidance on this topic?
Step-by-Step Procedure
Open the Role Registry
Go to /admin/rbac/roles. The heading is "Role Registry" with a count of roles.
Click "New Role"
The dialog "Create Role" opens with defaults: Type CUSTOM, Tier 4, Min Clearance 2, Data Scope TENANT.
Fill the identity fields
"Role Key" (for example treasury_auditor; it cannot be changed later), "Name" and "Description".
Set type, scope, tier and clearance
"Type" (SYSTEM, CUSTOM, TEMPORARY, SCOPED, SERVICE), "Data Scope" (GLOBAL, TENANT, WORKSPACE, ORGANIZATION, REGION, TEAM, DEPARTMENT, OWN, OWNED, ASSIGNED, CREATED_BY_USER, DOWNLINE, CUSTOM), "Tier (1-6)" and "Min Clearance (1-5)".
Add permissions
"Direct Permissions" takes comma or newline separated keys. "Denied Permissions (separation of duties)" takes keys the role must never receive. Keys must look like module.resource.action (letters, digits, underscore, separated by dots or colons) or "*".
Save
Click "Save Role". The button shows "Saving…" and the new role card appears in the grid.
The role appears in the registry at version 1 and is available in the Assignments and Mesh screens. The change is written to the governance audit chain.
Troubleshooting & Failure Modes
Was this guide helpful?
Help us refine our platform documentation