Custom Roles
Define roles tailored to your organization when none of the six built-in roles fit. Custom roles live in the Role Definitions card on Settings > Users, below the access grants table.
On This Page
Permissions
The Role Definitions card is only visible to administrators with the Manage Roles permission. Without it, the entire card is hidden.
The Role Definitions Table
The table defaults to showing custom roles only. Tick Show Built-in to add the six built-in roles (read-only, info icon only).
- Type
- Badge: Built-in (gray) or Custom (outline).
- Permissions
- The number of permissions in the role.
- Assigned
- How many users and groups currently hold this role.
- Actions
- Info icon for any role; pencil (edit) and trash (delete) for custom roles only.
Creating a Custom Role
Click Create Custom Role at the top right of the Role Definitions card. The same dialog handles create and edit.
- Role Name (required, up to 50 characters). Must be unique, comparison is case-insensitive.
- Description (optional, up to 200 characters). Use it to record why the role exists, future administrators will thank you.
- Permissions (required). Expand a category and check the permissions you want. Each category has its own master checkbox.
- Click Save. Disabled until the name is filled in and at least one permission is selected.
Permission categories
Resource Access
Viewing resources, costs, activity logs, and change tracking.
Security & Compliance
Defender, Advisor, and Policy permissions.
Scanning & Operations
Running scans, scanner settings, schedules, and the ignore list.
System Settings
Application settings, notifications, and audit logs.
Custom roles cannot include Administration permissions
Manage Users, Manage Roles, and other Administration permissions are reserved for the built-in Administrator role and don't appear in the dialog. If you need someone to manage users, assign them the built-in Administrator role.
Permission Dependencies
Some permissions need others. The dialog handles this automatically:
- Selecting a write or manage permission auto-selects its corresponding read permission. The read becomes locked and labelled (required) until you deselect the write.
- Some read permissions depend on View Scans (for example, View Cost Data and View Defender Findings). Selecting any of those auto-selects and locks View Scans.
- Deselecting a read permission automatically deselects every write or manage permission that depended on it.
Editing a Custom Role
Click the pencil icon on a custom-role row. The Edit Custom Role dialog opens with the current name, description, and permissions pre-filled.
Renaming is safe
Existing grants stay attached to the role through a rename, no further action is needed.
Deleting a Custom Role
Click the trash icon to open the Delete Custom Role dialog and confirm.
Assigned roles can't be deleted
If a role is assigned to any user or group, the trash icon is disabled. To delete it, first reassign every grant to a different role, find them by filtering the access grants table by the role you want to remove.
Troubleshooting
"Role name already exists"
What to check
Pick a different name. The comparison is case-insensitive, so Auditor and auditor count as the same name.
I can't deselect a read permission
What to check
Something else depends on it, look for the (required) label. Find the dependent write or manage permission, deselect it first, and the read will unlock.