---
title: Roles and Permissions
description: "Everything a staff member can do in RackHelm comes from the roles on their account. A role is a named bundle of permissions plus a position in a ranked list, and that ranking does real work: a role automatically inherits…"
url: "https://rackhelm.com/documentation/roles-and-permissions/"
updated: "2026-09-24"
category: "Clients, Staff & Access Control"
---

# Roles and Permissions

Everything a staff member can do in RackHelm comes from the roles on their account. A role is a named bundle of permissions plus a position in a ranked list, and that ranking does real work: a role automatically inherits everything held by the roles beneath it. This article covers the ranking, the editor and the rules that stop the system being used to escalate privileges.

## Before you start

> **Note:** Viewing roles requires `view_roles`; creating, editing and deleting require `create_roles`, `edit_roles` and `delete_roles`. In a default installation only Super Admin holds the edit and delete keys.

> **Tip:** The sidebar entry **Users & Roles → Roles & Permissions** is only rendered for Super Admin accounts. Other staff holding `view_roles` can still reach the screen by going to `/admin/roles` directly.

## How the hierarchy works

Roles are held in one ordered list. The role at the top has rank 1 and is the most privileged; each rank below it is less so. In a fresh installation that list reads Super Admin, Administrator, Billing Manager, Support Agent, Client.

Two consequences follow, and both surprise people the first time:

- **Roles inherit downwards.** A role holds its own permissions plus every permission held by every role positioned below it. Billing Manager sits above Support Agent, so a Billing Manager can also reply to tickets and manage canned replies even though nobody ticked those boxes on the Billing Manager role.
- **Rank bounds what you may touch.** You can only edit, reorder or delete a role positioned strictly below your own highest role, and you can only manage user accounts the same way.

The default client role is the exception to inheritance in both directions: it inherits nothing, and nothing inherits from it. That is what stops a new staff role, created low in the list, from handing its permissions to your entire customer base.

## The roles list

![The Roles and Permissions list showing rank arrows, permission counts, user counts and type badges](/wp-content/uploads/rackhelm-docs/clients-roles-index.png)
The permission count is the *effective* total — own permissions plus everything inherited from below.

| Column | Meaning |
| --- | --- |
| **Rank** | The role's position, with arrows to move it up or down. Moving a role changes what it inherits and what inherits from it. |
| **Role** | Name, plus a **Default client** badge on the role given to self-registering customers. |
| **Permissions** | Effective permissions out of the 88 that exist. |
| **Users** | How many accounts hold the role. |
| **Type** | **Built-in** for the five seeded roles, **Staff** for a custom role with admin access, **Custom** otherwise. |

The delete button only appears when a role is safe to remove: it is not the default client role and no account holds it. After a deletion the remaining ranks are renumbered so there are no gaps.

## Creating a role

1. Select **New Role**.
2. Enter a **Role Name** — required and unique.
3. Turn on **Staff role** if holders should reach the admin area and be assignable to support departments. Only a Super Admin's setting here is honoured.
4. Optionally set an **AI SEO Free Scans Override**: a whole number of free scans for holders of this role, or blank to fall back to the global `ai_seo_free_scans` setting. The field accepts `-1` and above. Where an account holds several roles, the highest override wins.
5. Select **Create Role & Set Permissions**. You are returned to the list; open the role to grant permissions.

![The New Role Definition form with role name, staff role switch and AI SEO free scans override](/wp-content/uploads/rackhelm-docs/clients-role-create.png)
The role is created empty — permissions are granted afterwards in the editor.

> **Note:** A new role is always inserted immediately *above* the default client role, never at the bottom of the list. Move it up afterwards if it should outrank Support Agent or Billing Manager.

## The permission matrix

Opening a role gives you a master–detail screen: a rail of every role on the left, the selected role's permissions on the right. Clicking another role in the rail switches straight to it, which makes comparing two roles quick.

![The role editor with the role rail on the left and grouped permission switches on the right](/wp-content/uploads/rackhelm-docs/clients-role-permission-matrix.png)
Inherited permissions are shown switched on, greyed, locked and tagged **Inherited** — they belong to a role below this one and cannot be turned off here.

- The badge beside the role name counts granted permissions out of the total, and updates as you flick switches.
- Permissions are collected into groups. Each group header carries its own count and an **All** switch that turns every toggleable permission in that group on or off. Clicking the header collapses the group.
- **Filter permissions** narrows the whole matrix as you type and expands any group that contains a match.
- **Staff role** and **AI SEO free scans** sit in the header, so you can adjust them without leaving the screen.
- Built-in role names are fixed; the name field is only editable on custom roles.
- **Save permissions** at the bottom writes the change. Only the switches you actually control are saved — inherited entries are never copied onto the role, so they keep tracking the role they come from.

For what each individual switch controls, see [Permission Reference](/docs/permission-reference/).

## Rules the editor enforces

- You cannot edit or delete a role that is **assigned to you** — this is what stops someone editing their way out of a limit.
- You cannot edit or delete a role ranked at or above your own.
- Only a Super Admin can edit the **Super Admin** role.
- You cannot grant a permission you do not hold yourself. Attempting it fails with the offending key named.
- The **default client** flag has no control on this screen — the roles list shows it only as a badge. The save handler still guards it, holding any attempt to move it to the same bar as granting the role's permissions directly, including everything it inherits.
- The default client role cannot be deleted.

## When changes take effect

Each account's effective permission set is cached for 24 hours, because it is consulted on every request. RackHelm clears that cache for you whenever it matters: saving a role, reordering roles, deleting a role and changing a user's role assignments all flush it, and reordering flushes it for *every* account because inheritance means one move can change what unrelated roles hold. Changes made straight in the database bypass all of this and will appear to do nothing for up to a day.

> **Warning:** Re-running the database seeders — including the `php artisan migrate --seed --force` that the installer runs — re-applies the built-in permission sets to Super Admin, Administrator, Billing Manager, Support Agent and Client, discarding any customisation you made to those five. Custom roles you created yourself are untouched. If you need a variation on Administrator, copy it into a new role rather than editing the built-in one.

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| A permission switch is on but greyed out with a padlock. | It is inherited from a role below this one. Turn it off on that lower role, or move this role below it. |
| "You cannot assign the permission '…' because you do not possess it." | You are trying to grant something you do not hold. Ask a Super Admin, or have the permission granted to your own role first. |
| "You cannot edit a role that is currently assigned to you." | By design. Use a higher-ranked account. |
| "You can only modify roles that are positioned lower than your highest role in the hierarchy." | The target role ranks at or above yours. |
| "Cannot delete a role that has users assigned to it." | Move those accounts to another role first — the **Users** column tells you how many. |
| A role suddenly holds permissions you never granted. | It was moved up the list, or a role beneath it gained permissions. Check the ranks; inheritance is always downwards. |
| Customers gained an admin capability. | Permissions were ticked directly onto the role carrying the **Default client** badge. That role never inherits, so anything it holds was granted to it by hand. Open it and clear the switches — its effective permission count should read 0. |
| Your carefully tuned Administrator role reverted after an upgrade. | The seeder ran. Rebuild it as a custom role. |