8. Roles Ranking

Roles are arranged by rank to control who can create or assign roles at different privilege levels. A user can only manage (create/edit/assign) roles with a rank equal to or below their own. Higher‐ranking roles appear at the top of the list (with lower rank numbers, such as 1), while lower‐ranking roles appear below.

Use Cases

Role-Based Access Control
A user can only manage (create/edit/assign) roles with a rank equal to or below their own, preventing unauthorized privilege escalation and ensuring secure role management.
Secure Role Visibility
Users can only see roles at or below their rank when creating or managing employees, eliminating confusion and maintaining appropriate permission levels.
Efficient Role Management
Admins can drag and drop roles to adjust the hierarchy, ensuring role privileges align with organizational needs and simplifying role administration.

1. Viewing the Roles Table

When you click Roles in the left-hand nav, the main pane displays every role in a table sorted by “Rank” (highest privilege at the top).

Rank: A number in the first column (1 = highest privilege), automatically assigned by order.
Unique label: The role’s machine-name, shown under the “Unique label” header.
Modules: A list of module-tags showing what each role can access (e.g. Projects, Desks, Clients). Only the first few tags appear, with a “+X Show all” link to expand.

Actions Icons

To the right, under Actions, there are three icons:

👥 Users: View/assign employees who hold this role
✎ Edit: Open the Edit-role panel to adjust permissions or template
🗑️ Delete: Permanently remove the role

2. Editing a Role

Click the ✎ pencil icon under Actions for the role you want to change.
The Edit role drawer appears, listing every module with View/Manage checkboxes (e.g., View own, View all, Manage own, Manage all).
Check or uncheck permissions as needed, then click Save.

3. Changing Role Rank (Drag‐and‐Drop)

Why? Drag-and-drop lets you reorder the hierarchy of roles—higher in the list = higher privilege.

3.1. Locate the Drag Handle

Look at the very left edge of the Rank column (the first column).
You’ll see a small vertical “pill” of dots (⋮⋮) next to each role’s row.
Hovering over it changes your cursor to a “move” icon.

3.2. Move the Role Up/Down

Click & Hold the dotted handle on the role you want to move.
Drag the entire row up to give it a higher priority (lower rank number), or down for lower.
Release to drop it into its new slot.

The role’s Rank automatically updates to reflect its new position. For example, if you move a role above another that had a lower rank number, the dragged role now has a higher privilege (lower rank number).

3.3. Effect on Visibility

Security safeguard: If you drag a role above your own rank, you will no longer see it in any Role dropdowns when assigning to employees or tokens.
Prevents privilege escalation: A rank-4 user can’t promote themselves (or others) to rank 3 or higher.

4. Assigning Roles to Employees or Tokens

After ranking roles appropriately, you’ll assign them—but you’ll only ever see roles at or below your own rank.

4.1. Add Employee

In the left-hand nav, click Employees.
In the top-right of the Employees table, click + Add.

In the Add employee drawer, locate the Role dropdown under General.
Only roles whose rank is at or below your rank appear.

4.2. Create Identification Token

In the left-hand nav, expand Security and click Identification tokens.
Click + Add at the top right of the Tokens table.
In the Add identification token drawer, find the Role dropdown.
Again, only roles at or below your rank are listed—higher-rank roles are hidden.

For instance, if your user is rank 4, you’ll only see rank 4, 5, 6… roles listed—rank 3 or above won’t appear.

Why Role Ranking Matters

Security: Prevents unauthorized privilege escalation (e.g., a mid‐level user granting themselves “super admin” powers).
Project Scope: Ensures a manager who only oversees one project can’t create or assign roles that exceed their scope.
Consistency: Keeps the system organized, with each user limited to assigning roles matching their authority level.

Example Scenario

1. Admin Role at Rank 4

The “admin” user sees and can assign roles at rank 4, 5, 6, etc.

2. QATestRole at Rank 5

Admin at rank 4 can't drag roles above it's own rank order(4).

This ensures Admin doesn’t accidentally (or intentionally) grant privileges beyond their own.

In short, Role Ranking is a fundamental security feature. It keeps your platform's environment safe by ensuring users can only create, assign, or manage roles at or below their rank, preventing privilege escalation and maintaining clear permission boundaries across the platform.