RBAC Permissions Matrix
Purpose
This page documents the Role-Based Access Control (RBAC) model for Maqsafy dashboards and APIs.
The purpose of this matrix is to prevent unauthorized access, privilege escalation, cross-tenant data exposure, and incorrect access to financial or credential-related actions.
Roles
| Role / Account Category | Description | Scope |
|---|---|---|
| Admin | Platform administrator with full governance and configuration access | Platform-wide |
| Employee | Internal or operational account category that may include manager, seller, parent, supplier, supplier driver, operator, supervisor, staff, automated call driver, and service provider account types | Based on assigned permissions and scope |
| School Manager | School management account that can manage school operations and may be linked to more than one school | One or more assigned schools only |
| Supplier | Supplier account that manages its own products, orders, and invoices | Assigned supplier only |
| Operator | Operator account that may manage more than one cafeteria | Assigned cafeterias only |
| Service Provider | Service provider account type used for service-related workflows | Assigned service provider scope |
| Supervisor | Supervisor account/type used for operational supervision workflows | Assigned scope |
| Student | Student account/category used for student-related access and flows | Own student scope only |
Confirmed Scope Rules
| Scope | Confirmed Rule |
|---|---|
| School Manager | Can be linked to more than one school and must only access assigned schools |
| Supplier | Can only access its own products, orders, and invoices |
| Operator | Can be linked to more than one cafeteria and must only access assigned cafeterias |
| Student | Access is limited to the student's own permitted scope |
| Cross-tenant access | Blocked unless the account is explicitly assigned to that scope |
Access Control Principles
- Enforce RBAC on every protected API endpoint.
- Enforce tenant scope on every database query.
- Do not rely on frontend UI hiding alone.
- Backend authorization must be mandatory.
- Sensitive actions must be audited.
- Financial and credential-related actions must have stricter authorization.
- Any cross-tenant access must be blocked by default.
- Unknown permissions must default to deny.
Permission Levels
| Level | Meaning |
|---|---|
| None | No access |
| View | Can read records only |
| Create | Can create new records |
| Update | Can modify existing records |
| Delete / Deactivate | Can deactivate or remove records where policy allows |
| Approve | Can approve workflow actions |
| Export | Can export data |
| Admin Only | Restricted to Admin role only |
High-Level Permission Matrix
| Area / Action | Admin | School Manager | Supplier | Operator |
|---|---|---|---|---|
| View dashboard | View | View | View | View |
| Manage platform settings | Update | None | None | None |
| Manage schools | Create / Update / Deactivate | View / Update within scope | None | None |
| Manage cafeterias / branches | Create / Update / Deactivate | View / Update within school scope | None | View / Update assigned scope |
| Manage dashboard users | Create / Update / Deactivate | None | None | None |
| Assign roles and scopes | Update | None | None | None |
| View permissions matrix | View | None | None | None |
| Manage school staff supervisor records | View | Create / Update within school scope | None | None |
| Assign supervisors to cafeterias | View | Create / Update within school scope | None | None |
| Import / sync students | View | Create / Update within school scope | None | None |
| View student records | View | View within school scope | None | None |
| Manage student spending policies | View / Update | Update within school scope | None | None |
| Manage product master catalog | Create / Update | None | Create / Update supplier products where allowed | Update availability where allowed |
| Manage school product allowlist / denylist | View / Update | Update within school scope | None | None |
| Manage menu schedules | View / Update | Update within school scope | None | Update where allowed |
| View purchase orders | View all | View within school scope | View assigned supplier orders | View assigned cafeteria orders |
| Create purchase orders | View / Update | None | None | Create where permitted |
| Accept / reject purchase orders | View | None | Update assigned orders | None |
| Confirm receiving | View | View within school scope | None | Update assigned cafeteria orders |
| View invoices | View all | View within school scope | View supplier invoices | View assigned cafeteria invoices |
| Export invoices / settlements | Export all | Export within school scope where allowed | Export supplier scope | Export operator scope where allowed |
| View wallet balances | View all | View within school scope where allowed | View supplier wallet | View cafeteria wallet |
| View immutable ledger | View all | View within school scope where allowed | View supplier ledger | View cafeteria ledger |
| Submit withdrawal request | Approve / Reject | None | Create where allowed | Create where allowed |
| Approve withdrawals | Approve | None | None | None |
| Initiate refund / return request | View / Update | View within school scope | Review where applicable | Create assigned transaction requests |
| Approve / reject refund request | Approve where configured | Approve where configured | Approve supplier returns where applicable | None |
| View reports | View all | View school reports | View supplier reports | View operator reports |
| Export reports | Export all | Export within school scope | Export supplier scope | Export operator scope where allowed |
| Manage advertisements | Create / Update | Create / Update school-level where enabled | None | Create / Update where enabled |
| Manage support tickets | View / Update all | Create / Update own scope | Create / Update own scope | Create / Update own scope |
| View audit logs | View all | None or limited by policy | None | None |
| Manage integration settings | Update | None | None | None |
Credential Permissions Matrix
Credential actions require special handling because credential identifiers are linked to student wallet access and lifecycle events.
| Credential Action | Admin | School Manager | Parent | Student | Supplier | Operator |
|---|---|---|---|---|---|---|
| View credential inventory | View all | View assigned school inventory | None | None | None | None |
| View credential identifier / code | View where policy allows | View where policy allows | None | None | None | None |
| Assign credential to student | Create / Update | Create / Update within school scope | None | None | None | None |
| Record delivery status | View / Update | Update within school scope | None | None | None | None |
| Cancel credential | Admin Only | None | None | None | None | None |
| Activate / deactivate credential | Update according to configured permissions and assigned scope | Update within school scope according to configured permissions | Update own student scope according to configured permissions | Update own scope according to configured permissions | None | None |
| Replace credential | Needs Technical Verification | None | None | None | None | None |
| View credential lifecycle history | View all | View within school scope where allowed | None | None | None | None |
| Export credential distribution report | Export all | Export assigned school scope | None | None | None | None |
SRS Alignment Note — Credential Lifecycle Permissions
The previous SRS document stated that credential deactivation and replacement are Admin-only actions.
The technical management team has confirmed the following updated policy:
- Cancellation is Admin-only.
- Activation / deactivation can be performed by School Manager, Parent, and Student only according to configured permissions and assigned scope. This must not be interpreted as unrestricted access.
- Replacement policy has not been fully confirmed. This item is marked as Needs Technical Verification and should not be treated as Admin-only based on SRS alone until the technical team provides confirmation.
This note must remain in documentation until the SRS is formally updated or the technical team provides a written decision on credential replacement authorization.
Tenant Isolation Rules
| Rule | Description |
|---|---|
| School isolation | School Manager must only access records under assigned school scope |
| Supplier isolation | Supplier must only access products, orders, invoices, returns, and wallet data assigned to that supplier |
| Operator isolation | Operator must only access assigned cafeteria/operator records |
| Admin auditability | Admin can access platform-wide data, but sensitive actions must be logged |
| Default deny | If scope cannot be verified, the request must be denied |
Backend Enforcement Requirements
Every protected endpoint must verify:
- User is authenticated.
- User role is allowed.
- User permission allows the requested action.
- User scope matches the target resource.
- Sensitive action is audited.
- Response does not include fields outside the user’s permission scope.
Example Authorization Checklist
Use this checklist when creating or reviewing an endpoint.
| Check | Required |
|---|---|
| Authentication middleware applied | Yes |
| Role check applied | Yes |
| Permission check applied | Yes |
| Tenant scope filter applied | Yes |
| Sensitive fields filtered | Yes |
| Audit log added for sensitive action | Yes |
| Test added for unauthorized access | Yes |
| Test added for cross-tenant access | Yes |
Example: School Manager Access Rule
A School Manager can only access students where:
student.school_id IN assigned_school_ids
Invalid access example:
School Manager from School A requesting Student from School B
Expected result:
403 Forbidden
Example: Supplier Access Rule
A Supplier can only access purchase orders where:
purchase_order.supplier_id = authenticated_supplier_id
Expected unauthorized result:
403 Forbidden
Example: Operator Access Rule
An Operator can only access cafeteria records where:
cafeteria.operator_id = authenticated_operator_id
Expected unauthorized result:
403 Forbidden
Audit Requirements
The following actions must be audited:
- Login failures
- User creation or deactivation
- Role and permission changes
- School or cafeteria changes
- Student import or status changes
- Wallet balance adjustments
- Refund actions
- Withdrawal approvals
- Credential assignment
- Credential delivery update
- Credential deactivation
- Credential replacement
- Export of sensitive reports
- Integration configuration changes
Audit Log Fields
| Field | Description |
|---|---|
| actor_id | User who performed the action |
| actor_role | Role of the actor |
| action | Action performed |
| resource_type | Target entity type |
| resource_id | Target entity ID |
| tenant_scope | School / supplier / operator scope |
| before_value | Previous value where applicable |
| after_value | New value where applicable |
| ip_address | Request IP, where available |
| user_agent | Device or browser metadata, where available |
| created_at | Timestamp |
Testing Requirements
RBAC must be tested using positive and negative cases.
| Test Case | Expected Result |
|---|---|
| Admin accesses platform-wide records | Allowed |
| School Manager accesses assigned school records | Allowed |
| School Manager accesses another school records | Denied |
| Supplier accesses assigned supplier order | Allowed |
| Supplier accesses another supplier order | Denied |
| Operator accesses assigned cafeteria record | Allowed |
| Operator accesses another cafeteria record | Denied |
| School Manager cancels credential | Denied |
| Admin cancels credential | Allowed |
| School Manager activates / deactivates credential within assigned school | Allowed where permissions configured |
| Parent activates / deactivates own student credential | Allowed only where configured permissions allow for the parent/student relationship |
| Student activates / deactivates own credential | Allowed only where configured permissions allow for the student's own scope |
| Unauthenticated user accesses protected endpoint | Denied |
| User exports report outside scope | Denied |
Review Status
| Item | Status |
|---|---|
| RBAC roles confirmed | Confirmed — Admin, Employee (with sub-types), Student |
| Permissions confirmed with product owner | Confirmed — See Technical Verification Update in Documentation Review Checklist |
| Backend middleware implemented | Needs Technical Verification |
| Tenant isolation tested | Confirmed by technical team; Evidence Pending |
| Audit logs implemented | Needs Technical Verification |
| Negative access tests implemented | Needs Evidence |
| Sensitive exports reviewed | Needs Technical Verification |
| Credential cancellation Admin-only | Confirmed |
| Credential activation/deactivation policy | Confirmed — according to configured permissions and assigned scope; Evidence Pending |
| Credential replacement policy | Needs Technical Verification |
| SRS alignment note added | Yes — See Credential Permissions Matrix above |
Security Rules
- Do not grant access based only on frontend visibility.
- Do not trust user-submitted scope IDs.
- Always derive scope from authenticated user context.
- Do not expose student data outside authorized school scope.
- Do not expose supplier or operator records across tenants.
- Do not allow credential deactivation or replacement outside Admin role.
- Deny by default when permission or scope is unclear.