SIGNALS Docs

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.

Embedding settings changes and consent require this owner flag as well as the normal settings permission and token ability. Granting settings.manage to another role does not allow it to enable embeddings, change their credentials, or grant or revoke consent.

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.

Rental point-in-time snapshots (GET /api/v1/rentals/{rental}/as_at) require both rentals.view and action-log.view, with token abilities rentals:read and action-log:read. REST calls and the MCP get-entity-as-at tool enforce these grants, matching account, invoice, and catalogue item snapshots.

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

  1. Basics — name, description, and optional start-from (blank, a built-in preset you are allowed to use, or an existing custom role).
  2. 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.
  3. 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).
  4. 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.

At a glance

Create and manage roles for permission-based access control. Create role opens the role builder wizard (capabilities → refine → review). Custom roles can also be edited with the wizard; system presets are locked and must be duplicated first.

Action Description
Create Role Opens the role builder wizard
Edit with wizard Re-open the wizard for a custom role
Inline editor Layer tabs + grant grid with bulk group toggles
Delete Remove a non-system role (only if no users are assigned)

System roles cannot be deleted. Role hierarchy prevents duplicating or starting from a role at or above your own level.

/admin/settings/permissions is not a sidebar item — it redirects to the role editor. Permissions follow the resource.action naming convention (e.g. rentals.create, invoices.issue) and carry capability tags for the wizard. Plugins can register additional permissions (optionally with capability tags).