Permissions model

Goal

Understand how BlueMatrix authorizes staff actions with permission keys, roles, modules, and token abilities.

Who it is for

Tenant admins configuring access; managers diagnosing “I cannot see / do X”.

Preconditions

• member.view to browse members; member.admin to edit Advanced catalogs; role.manage to open Members setup, read catalogs, and create roles (wizard or matrix).

How it works

1. Permission keys live in Permissions::catalogue() (e.g. sales.view, sales.manage, sales.post).
2. Roles (Owner, Admin, Manager, Member, CRM Member, plus custom) grant keys. Owner effectively has *.
3. Modules gate entire areas: frontend meta.module / auth.hasModule; API disabled module → 422.
4. SPA checks: auth.can(key) hides nav and actions; failing meta.permission redirects to dashboard (not a 403 page).
5. API checks: controllers call $this->authorize(…) → 403 when denied.
6. Tenancy: Sanctum ability tenant:{uuid}; never trust body/query tenant_id. Cross-tenant rows → 404 (RLS).

Steps (admin)

1. Open Members → Members setup.
2. Use Create role for a guided job + capabilities role (role.manage can load the catalogs), or Advanced to curate templates and packs.
3. Adjust the Permission matrix for custom roles.
4. Assign roles on memberships; ask the user to refresh / re-login if keys changed.

Result

Users only see and call what their membership allows; optional modules stay dark when entitlement is off.

Hard stops

Missing member.admin blocks matrix edits; confusing 403 (no permission) with 404 (hidden/other tenant) and 422 (module/business rule).

Related

• Troubleshoot permissions
• Users and roles
• Tenant admin hub