API Authentication

Purpose

This page documents the authentication and authorization approach for Maqsafy APIs and dashboards.

Authentication Scope

Authentication applies to dashboard users and API consumers based on the assigned role and permission scope.

Main dashboard roles:

Role	Scope
Admin	Platform-wide administration
School Manager	Assigned school scope
Supplier	Supplier-specific operations
Operator	Assigned cafeteria/operator scope

Authentication Flow

1. The user submits login credentials.
2. The system validates the credentials.
3. OTP verification may be required depending on the flow.
4. The system issues an access token after successful verification.
5. The client sends the access token in subsequent requests.
6. The backend validates the token and checks role-based permissions.

Authorization Header

Authorization: Bearer <ACCESS_TOKEN>

Login Request Example

POST /api/login
Content-Type: application/json

{
  "mobile": "05XXXXXXXX",
  "password": "********"
}

Success Response Example

{
  "token": "example-access-token",
  "user": {
    "id": 1,
    "name": "Example User",
    "role": "school_manager"
  }
}

Role-Based Access Control

The system must enforce RBAC across all dashboard users, API endpoints, and data access operations.

Control	Description
Role	Defines the user type, such as Admin or School Manager
Permission	Defines the action allowed for the user
Scope	Defines the data boundary, such as school, supplier, or cafeteria
Audit	Records sensitive actions for traceability

Sensitive Actions

Examples of actions that should require strict authorization:

• Managing dashboard users
• Changing role permissions
• Viewing financial reports
• Approving withdrawals
• Processing refunds
• Managing credential inventory
• Deactivating or replacing credentials
• Exporting sensitive reports

Authentication Event Logging

The system should log authentication-related events, including:

• Successful login
• Failed login
• Password reset request
• OTP verification attempt
• Logout
• Suspicious login behavior, where applicable

Security Rules

• Do not document real access tokens.
• Do not document real OTP values.
• Do not include real user credentials.
• Do not expose SMS provider keys.
• Do not include real session IDs or cookies.
• Use placeholders in all examples.