Roles & Permissions

How access is decided across the whole console: permissions are seeded in code, roles bundle them, and a user's effective access is simply the union of every permission on every role they currently hold.

The role-only model

There is no way to grant a permission to a person directly — access always flows permission → role → user. This is deliberate: it keeps access auditable (you can always answer "why can they do that?" by looking at their roles) and keeps individual exceptions out of the system.

Two access-gate styles exist side by side in the console today. A handful of setup-style resources — including this page's own two resources, plus Warehouses, Geography and most of Customers — check isSuperAdmin() only, with no granular permission string honoured at all, even where one is seeded (e.g. admin.manage_roles, admin.manage_users). Everything else checks isSuperAdmin() || hasPermission('module.action'). Practically: today, only super_admin role holders can reach the pages on this page, regardless of any other permission granted to them.

Roles Built

Nav location: Access Control → Roles & Permissions lists roles first. Access: super-administrator only.

List columns

There are no filters on this list.

Creating or editing a role

1. Select New role (or a row to edit)
2. Set the Name (slug)

   A short, code-friendly identifier such as sales_manager — required, max 100, unique. On a system role this field is disabled; you cannot rename it.

3. Set the Display Name

   What people actually see in the console — required, max 150.

4. Optionally add a Description

   Free text explaining the role's purpose.

5. Save

   Permissions are not assigned on this form — see the Permissions tab below, which appears once the role exists.

Assigning permissions to a role Built

Open a role for editing and use its Permissions tab. Permissions are never created or edited here — only attached to, or detached from, the role. The table is grouped by module by default, so you can see at a glance how much of one module (e.g. all of billing) a role already covers.

1. Open the role, then its Permissions tab
2. Select Attach

   Opens a picker preloaded with every permission in the system, searchable by name.

3. Choose one permission and confirm

   Repeat for each permission the role needs — there is no multi-select in the attach picker, and no "assign whole module at once" bulk action. Building a role that should cover, say, all of billing means attaching each billing.* permission individually.

4. Remove a permission with row Detach

   Or select several rows and use the bulk Detach action. Detaching never deletes the permission — only the role's grant of it.

Permissions Built (view-only)

Nav location: Access Control → Roles & Permissions, the Permissions list. Access: super-administrator only. Every permission is seeded in code and always carries is_system = true — there is no way to create, edit or delete a permission from this screen. Its canCreate() check is explicitly hardcoded to always refuse, so you will not even see a New button here.

List columns

Filters

A single Module filter, built dynamically from whatever module names actually exist in the database — it is never a hardcoded list, so it always matches reality even as new modules are seeded.

There are no row actions at all on this list — no Edit, no Delete. Select a row to open its view page instead.

The permission's view page

Two read-only sections:

Permission modules at a glance

Permissions are grouped by a module field. The table below summarises the breadth by module with a few representative examples — it is not the full list. For every seeded permission name, see the Glossary reference page.