Roles & permissions
Build custom roles with the capability wizard, refine granular grants, and understand four-layer authorisation.
Overview
Signals authorises every screen and API call through roles that hold a set of permissions. Built-in system roles (Admin, Operations Manager, Sales, Warehouse, Read Only) ship ready to use; custom roles are built with the role builder wizard.
Route: /admin/settings/roles (requires roles.view / roles.manage)
Owner access is not a Spatie role — it is the users.is_owner flag and always bypasses role checks.
Four authorisation layers
| Layer | What it answers | How it is configured |
|---|---|---|
| 1. UI areas | Can you open this area? | *.access permissions |
| 2. Actions | Can you perform this action? | resource.action permissions |
| 3. Cost visibility | Can you see costs & margins? | costs.view and the role’s cost-visibility flag |
| 4. Warehouse scoping | Which warehouses’ data can you see? | Role all_warehouses flag vs per-user warehouse membership |
The access simulator on the roles page (and on the wizard review step) traces a permission through all four layers for a chosen role and optional warehouse.
Role builder wizard
Create role opens the wizard (not a bare name form). Edit with wizard is available on custom roles. System presets stay locked — duplicate them first if you need a variant.
Steps
- Basics — name, description, and optional start-from (blank, a built-in preset you are allowed to use, or an existing custom role).
- Capabilities — high-level levels per area (None / View only / Full) for Money, Operations, CRM, Admin, and Reporting. Destructive actions (delete, void, cancel, dissolve, reinstate, override) are a separate toggle and default off. Cost visibility and all-warehouses access are plain-language flags on this step.
- Refine — the grouped permission grid, pre-filled from your capability choices, with bulk grant/clear per group and sub-group. Granting a permission pulls its dependency closure; revoking a prerequisite also revokes dependents (with a warning toast).
- Review — grant summary by capability, diff vs the nearest built-in preset, and a draft simulator. Save always goes through
CreateRole/UpdateRole— the same path as the inline editor.
Capability tags
Every core permission carries one or more capability tags used by the wizard:
| Tag | Covers |
|---|---|
money |
Invoices, payments, credits, costs, rates, pricing, purchase-order finance |
operations |
Stock, dispatch, returns, scanning, transfers, flightcases, repairs, equipment_tests |
crm |
Accounts, rentals, activities, conversations |
admin |
Settings, users, roles, system tools, integrations, imports |
reporting |
Reports, exports, documents |
destructive |
Explicit tag on delete / void / cancel / dissolve / reinstate / override grants |
Plugins registering permissions via PluginRegistrar::permission() may pass the same optional capabilities list so their grants participate in the wizard.
Hierarchy guard rails
Built-in roles sit on a numeric ladder (Owner → Admin → Operations Manager → Sales / Warehouse → Read Only). You can only assign, duplicate, or start-from roles strictly below your own level. Custom roles sit below every system role, so any elevated actor can manage them; they cannot be used to escalate past your level when inviting users.
Inline editor
The same page still offers the layer tabs and grant grid for fine-tuning after a role exists. Bulk group toggles and dependency closure behaviour are shared with the wizard. Unsaved changes show an apply/discard bar; success and failure use toasts.