Roles (Admin)

Executive summary

Roles define admin_roles.modules JSON exposed on JWT as modules: string[] | null. This page is the canonical explanation of null = full access vs array = keyed features (e.g. item for catalog).

---

Goals and non-goals

Goals	Non-goals
Align SPA behavior with backend guards	Edit Laravel DB by hand from this doc
Help debug 403 vs “sidebar still visible”	List every guard class

---

Current platform behavior

• modules === null: backend full module access (Master-style).
• Array: each string is a module key; missing keys → 403 on APIs (Admin overview).

---

Sequence: happy path

1. Open Roles list → create or edit role.
2. Set modules to null or explicit keys → save.
3. Assign managers to role → JWT reflects on next login/me.

---

Security and operations

• Least privilege: prefer explicit keys over null except true superusers.
• Changing keys is a release coordination step with backend ADMIN_PANEL_MODULE_* constants.

---

Test scenarios (UAT / QA)

ID	Scenario	Expected
R1	Role with item	Catalog APIs succeed
R2	Role without item	Catalog 403
R3	modules: null	Broad access per backend rules

---

Routes

• /dashboard/roles, /dashboard/roles/new, /dashboard/roles/:id, /dashboard/roles/:id/edit

/dashboard/roles/:id is now the detail page with:

• Subscribed customers = admin users assigned to that role.
• Plan details = permission modules and total permission count.

Admin role API endpoints

• GET /admin/roles
• GET /admin/roles/:id
• GET /admin/roles/:id/detail — role detail with subscribedCustomers and planDetails.permissionModules
• POST /admin/roles
• PATCH /admin/roles/:id
• DELETE /admin/roles/:id

Modules (admin_roles.modules)

• Stored as JSON on the role in the legacy Laravel schema; exposed on JWT login/me as modules: string[] | null (AdminLoginResponse / AdminMeResponse in apps/admin-web/src/types/admin-auth.types.ts).
• modules === null: backend treats this as full module access (Master Admin style). Guards such as AdminItemModuleGuard allow any module when modules === null.
• modules as an array: each string is a feature key (e.g. catalog is often item for products — see backend ADMIN_PANEL_MODULE_ITEM / product APIs). Restricted admins receive 403 when calling APIs for modules not in their list.

Master vs restricted

• Master admin (e.g. role_id 1 in Laravel parity — see admin-auth.controller API docs) typically has modules: null.
• Custom roles use an explicit module list; assign the minimum keys needed for each job function.

Sidebar vs module keys (practical map)

The admin sidebar does not read modules to hide links; enforcement is on the API. Known backend constant:

Module key	Used for (example)
item	Catalog / products (ADMIN_PANEL_MODULE_ITEM in apps/backend/src/modules/admin/admin.constants.ts; guarded by AdminItemModuleGuard).

Other areas (orders, stores, vendors, optional Zones registry) rely on service-level checks per controller — extend this table when new ADMIN_PANEL_MODULE_* constants and guards are added.

Optional follow-up

• Screenshot walkthrough of creating a role in /dashboard/roles.

Related

• Admin panel overview — modules on the session.
• Authentication — JWT and refresh.