masaruk Logo

Auth & Users API

Authentication and user management endpoints for MASARUK

1. Purpose

This document defines all authentication & user-management endpoints across MASARUK:

  • B2C end-user authentication (Web + Mobile)
  • Provider Portal authentication (B2B)
  • Admin Panel authentication
  • JWT token generation
  • Profile management
  • Password recovery
  • Social login integration (Google / Facebook)

This API layer is shared across:

  • Next.js Web Frontend
  • Flutter Mobile Apps
  • Admin Panel
  • Provider Portal

2. Auth Model Overview

2.1 Authentication Method

MASARUK backend uses:

  • JWT (jsonwebtoken) for all platforms.
  • HTTP-only cookies for secure web session refresh tokens.

2.2 Token Behavior

PlatformToken TypeStorageExpiry
Web (Next.js)JWT Access + Refresh TokenAccess: Memory, Refresh: HttpOnly CookieAccess: 15min-1h, Refresh: 7-30d
MobileJWTSecure StorageConfigurable (e.g., 30 d)
Provider PortalJWTAccess: Memory, Refresh: HttpOnly CookieConfigurable

2.3 Required Headers

Authorization: Bearer <token>

Accept: application/json

Content-Type: application/json

3. Entities Involved

User

(Arabic labels preserved as-is from UI)

FieldDescription
idPrimary key
full_name"الاسم بالكامل"
email"البريد الالكتروني"
phone"رقم الجوال"
password_hashHashed password
roleENUM: super_admin, admin, provider_admin, provider_staff, user
statusACTIVE / BLOCKED
created_atDate
updated_atDate

4. Endpoints

All endpoints below follow the standard error and validation patterns from api-principles-and-versioning.md.

POST/api/v1/auth/signup

Creates a new customer account.

Request Body:
{
  "full_name": "محمد أحمد",
  "email": "user@example.com",
  "phone": "966500000000",
  "password": "StrongPass123",
  "password_confirmation": "StrongPass123"
}
Validation Rules:
  • full_name: required, string
  • email: required, unique
  • phone: required, unique
  • password: required, confirmed
Example Response:
{
  "success": true,
  "token": "<jwt_token>",
  "user": {
    "id": 1,
    "full_name": "محمد أحمد",
    "email": "user@example.com",
    "phone": "966500000000",
    "role": "user"
  }
}
POST/api/v1/auth/login
Request Body:
{
  "email": "user@example.com",
  "password": "StrongPass123"
}
Example Response:
{
  "success": true,
  "token": "<jwt_token>",
  "user": {
    "id": 1,
    "full_name": "محمد أحمد",
    "email": "user@example.com",
    "role": "user"
  }
}
Error Cases:
401Invalid credentials
403Blocked user (status = BLOCKED)
POST/api/v1/auth/social

Used for both Google and Facebook.

Request Body:
{
  "provider": "google",
  "access_token": "<provider_token>"
}

Same shape as normal login (returns token + user).

POST/api/v1/auth/logout

Invalidates the current JWT token / session according to platform rules.

5. Profile Management

GET/api/v1/user/profile
Example Response:
{
  "id": 1,
  "full_name": "محمد أحمد",
  "email": "user@example.com",
  "phone": "966500000000",
  "role": "user"
}
PUT/api/v1/user/profile
Request Body:
{
  "full_name": "محمد أحمد",
  "phone": "966500000010"
}
PUT/api/v1/user/change-password
Request Body:
{
  "current_password": "oldPass123",
  "new_password": "NewStrong123",
  "new_password_confirmation": "NewStrong123"
}

6. Password Reset Flow

POST/api/v1/auth/forgot-password
Request Body:
{ "email": "user@example.com" }
Example Response:
{ "message": "Password reset link sent" }
POST/api/v1/auth/reset-password
Request Body:
{
  "token": "<reset_token>",
  "email": "user@example.com",
  "password": "NewPass123",
  "password_confirmation": "NewPass123"
}

7. Admin & Provider Authentication

POST/api/v1/provider/auth/login

Uses the same basic login flow but must return provider-specific fields.

Example Response:
{
  "token": "<jwt>",
  "user": {
    "id": 33,
    "role": "provider_admin",
    "provider_id": 7
  }
}
  • role is either provider_admin or provider_staff.
  • provider_id is the owning company.
POST/api/v1/admin/auth/login

Only super_admin or admin roles are allowed.

8. Status Mapping

For reference; full mapping lives in 00-guidelines/status-mapping-template.md.

Arabic (UI)Internal EnumNotes
نشط/فعّالACTIVEUnified internally
غير نشط / غير فعّالINACTIVE
ملغاهCANCELLEDUsed in bookings
مكتملةCOMPLETED
قيد التنفيذPENDINGCanonical internal ID

9. Error Patterns

Standardized across all endpoints.

401Unauthorized
{ "success": false, "message": "Unauthorized" }
422Validation Error
{ "errors": { "email": ["Email is required"] } }
500Internal Error
{ "message": "Server error" }