Help Center/Governance, RBAC & Security Desk/How to create a custom role in the Role Registry
Governance, RBAC & Security Desk•Last updated: 2026-10-20•3 min read

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?

Ask AI Copilot

Step-by-Step Procedure

1

Open the Role Registry

Go to /admin/rbac/roles. The heading is "Role Registry" with a count of roles.

2

Click "New Role"

The dialog "Create Role" opens with defaults: Type CUSTOM, Tier 4, Min Clearance 2, Data Scope TENANT.

3

Fill the identity fields

"Role Key" (for example treasury_auditor; it cannot be changed later), "Name" and "Description".

4

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

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

6

Save

Click "Save Role". The button shows "Saving…" and the new role card appears in the grid.

Expected Operational Outcome

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

Symptom: Role "x" already exists.
Likely Cause: The Role Key is taken.
Resolution: Choose another key.
Symptom: Invalid permission key "x". Expected module.resource.action
Likely Cause: A permission entry does not match the key format.
Resolution: Fix the typo; keys use only letters, digits, underscores and dot or colon separators.
Symptom: Authentication/permission error (401/403)
Likely Cause: You lack rbac.roles.manage.
Resolution: Ask a super admin.

Was this guide helpful?

Help us refine our platform documentation