Maham Auth Service - API Documentation

الميزات الرئيسية

JWT Authentication

مصادقة بتوكنات JWT مع دعم التجديد والإلغاء. صلاحية التوكن 480 دقيقة.

Roles & Permissions

نظام أدوار وصلاحيات متعدد المستويات مع دعم الرفض الصريح والصلاحيات المؤقتة.

Service-to-Service

تواصل آمن بين الخدمات عبر توكنات مخصصة مع التحقق من IP وتسجيل الأنشطة.

Service Roles

تحديد أدوار لكل خدمة للتحكم بمن يقدر يسجل دخول. إضافة وتعديل الأدوار ديناميكياً.

Audit Trail

تسجيل شامل لجميع الأحداث: تسجيل دخول، تغييرات الأدوار، تعديلات الصلاحيات مع تتبع IP.

Redis Caching

كاش ذكي للصلاحيات والأدوار لأداء سريع مع TTL قابل للتخصيص وتنظيف تلقائي.

المصادقة

Authentication

تسجيل الدخول، التسجيل، إدارة الجلسات والتوكنات

POST /api/v1/auth/register تسجيل مستخدم جديد public

Request Body

name required string - اسم المستخدم

email required email - البريد الإلكتروني (فريد)

password required string - كلمة المرور (min:8، أحرف كبيرة وصغيرة وأرقام)

password_confirmation required string - تأكيد كلمة المرور

phone required string - رقم الهاتف (فريد)

roles optional array - أسماء الأدوار

Response 201

{
  "success": true,
  "message": "تم التسجيل بنجاح",
  "data": {
    "user": {
      "id": "uuid",
      "name": "Ahmed",
      "email": "ahmed@example.com",
      "roles": ["user"]
    },
    "token": "eyJ0eXAiOiJKV1Qi..."
  }
}

POST /api/v1/auth/login تسجيل الدخول public

Request Body

identifier required string - البريد أو رقم الهاتف

password required string - كلمة المرور

ملاحظة: إذا الخدمة عندها أدوار محددة، لازم يكون عند المستخدم واحد من هالأدوار عشان يقدر يسجل دخول.

Response 200

{
  "success": true,
  "message": "تم تسجيل الدخول بنجاح",
  "data": {
    "user": {
      "id": "uuid",
      "name": "Ahmed",
      "email": "ahmed@example.com",
      "roles": ["admin"],
      "permissions": [...]
    },
    "token": "eyJ0eXAiOiJKV1Qi..."
  }
}

تسجيل الدخول بالجوال + رمز OTP

الطريقة الرئيسية لتسجيل الدخول عبر التطبيق — SMS أو WhatsApp

1 POST

/api/v1/auth/otp/send

phone required

user_type optional — يُكتشف تلقائياً

channel sms | whatsapp

يرسل رمز مكوّن من 6 أرقام عبر Authentica

2 POST

/api/v1/auth/otp/verify

phone required

code required 4-8 أرقام

user_type optional

→ مستخدم موجود: JWT Token

→ مستخدم جديد: registration_token

3 POST

/api/v1/auth/otp/complete-registration

registration_token required

name required

user_type required merchant | investor | sponsor

email optional

فقط للمستخدمين الجدد — يحدد نوع الحساب

⚡ المزود: Authentica (SMS + WhatsApp) — OTP_TEST_MODE مفعل حالياً، الرمز 123456

GET /api/v1/auth/me

auth

جلب بيانات المستخدم الحالي مع الأدوار والصلاحيات الكاملة

Header: Authorization: Bearer {token}

POST /api/v1/auth/refresh

auth

تجديد التوكن المنتهي. يرجع توكن جديد مع مدة الصلاحية

Response: { token, token_type, expires_in }

POST /api/v1/auth/logout

auth

تسجيل خروج المستخدم وإلغاء التوكن الحالي نهائياً

Header: Authorization: Bearer {token}

POST /api/v1/auth/change-password auth

تغيير كلمة المرور

current_password - كلمة المرور الحالية

password - كلمة المرور الجديدة

password_confirmation - التأكيد

PUT /api/v1/auth/profile auth

تحديث الملف الشخصي

name - الاسم

phone - رقم الهاتف

POST /api/v1/auth/forgot-password public

إرسال رابط استعادة كلمة المرور

email - البريد الإلكتروني

POST /api/v1/auth/reset-password public

إعادة تعيين كلمة المرور

token + email + password

POST /api/v1/auth/email/send-verification auth

إرسال رمز التحقق من البريد الإلكتروني

بدون حقول إدخال - يرسل رمز التحقق للبريد المسجل

POST /api/v1/auth/email/verify auth

التحقق من البريد الإلكتروني

code required - رمز التحقق المرسل للبريد

POST /api/v1/auth/phone/send-otp auth

إرسال رمز التحقق لتوثيق رقم الجوال

phone required - رقم الجوال

channel sms | whatsapp

POST /api/v1/auth/phone/verify-otp auth

تأكيد رقم الجوال بالرمز المرسل

phone required - نفس الرقم

code required - رمز التحقق

GET /api/v1/admin/stats/users auth users.view

إحصائيات المستخدمين للوحة تحكم الأدمن

إدارة المستخدمين

Users Management

عرض، إنشاء، تعديل وحذف المستخدمين مع إدارة الأدوار والصلاحيات

GET /api/v1/users قائمة المستخدمين users.view

POST /api/v1/users إنشاء مستخدم users.create

GET /api/v1/users/{id} تفاصيل مستخدم users.view

PUT /api/v1/users/{id} تحديث مستخدم users.update

DELETE /api/v1/users/{id} حذف مستخدم users.delete

POST /api/v1/users/{id}/roles تعيين أدوار roles.update

POST /api/v1/users/{id}/permissions تعيين صلاحيات permissions.update

GET /api/v1/users/{id}/permissions عرض صلاحيات permissions.view

الأدوار والصلاحيات

Roles & Permissions

نظام RBAC كامل لإدارة الأدوار والصلاحيات مع ربط متعدد المستويات

Roles

GET /api/v1/roles القائمة

POST /api/v1/roles إنشاء دور

GET /api/v1/roles/{id} التفاصيل

PUT /api/v1/roles/{id} تحديث

DELETE /api/v1/roles/{id} حذف

POST /api/v1/roles/{id}/permissions مزامنة الصلاحيات

POST /api/v1/roles/{id}/permissions/add إضافة صلاحيات

POST /api/v1/roles/{id}/permissions/remove إزالة صلاحيات

Permissions

GET /api/v1/permissions القائمة

POST /api/v1/permissions إنشاء صلاحية

POST /api/v1/permissions/resource إنشاء CRUD لمورد

GET /api/v1/permissions/{id} التفاصيل

PUT /api/v1/permissions/{id} تحديث

DELETE /api/v1/permissions/{id} حذف

POST /resource - ينشئ صلاحيات CRUD كاملة (view, create, update, delete) لمورد واحد

إدارة الخدمات

Services & S2S

تسجيل وإدارة الـ Microservices مع التواصل الآمن عبر Service Tokens

POST /api/v1/services تسجيل خدمة جديدة services.create

Request Body

name required string - اسم الخدمة (فريد)

display_name required string - الاسم المعروض

description optional string - الوصف

allowed_ips optional array - IPs المسموح بها

webhook_url optional url - رابط الـ Webhook

roles optional array - أدوار الخدمة (تحدد من يقدر يسجل دخول)

Response 201

{
  "success": true,
  "message": "تم تسجيل الخدمة بنجاح",
  "data": {
    "id": "uuid",
    "name": "expo-app",
    "token": "svc_xxx...",
    "secret": "sec_xxx...",
    "roles": [
      { "name": "admin" }
    ]
  },
  "warning": "احفظ التوكن والسر!"
}

تحذير: التوكن والسر يظهروا مرة وحدة فقط! لازم تحفظهم فوراً.

إدارة الخدمات - CRUD

GET /api/v1/services قائمة الخدمات services.view

GET /api/v1/services/{id} تفاصيل خدمة services.view

PUT /api/v1/services/{id} تحديث خدمة (+ roles sync) services.update

DELETE /api/v1/services/{id} حذف خدمة services.delete

POST /api/v1/services/{id}/regenerate-token تجديد التوكن services.update

GET /api/v1/services/{id}/roles عرض أدوار الخدمة services.view

POST /api/v1/services/{id}/roles إضافة أدوار للخدمة services.update

PUT /api/v1/services/{id}/roles مزامنة الأدوار services.update

DELETE /api/v1/services/{id}/roles إزالة أدوار services.update

Service-to-Service (S2S)

محمية عبر الشبكة الداخلية فقط

POST /api/v1/service/verify-token

التحقق من توكن المستخدم

Body: { "token": "jwt..." }

Returns: user data + roles

POST /api/v1/service/check-permission

التحقق من صلاحية المستخدم

Body: { "token", "permission" }

Returns: has_permission boolean

POST /api/v1/service/user-info

جلب معلومات المستخدم

Body: { "token": "jwt..." }

Returns: full user info

البدء السريع

Quick Start

أمثلة سريعة للبدء بإستخدام الـ API

Login with Service Name

curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "admin@auth-service.local",
    "password": "password",
    "service_name": "expo-app"
  }'

Register New User

curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ahmed Ali",
    "email": "ahmed@example.com",
    "password": "Password123",
    "password_confirmation": "Password123",
    "phone": "0501234567"
  }'

Service-to-Service Token Verification

curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/service/verify-token \
  -H "Content-Type: application/json" \
  -d '{
    "token": "user-jwt-token-here"
  }'

Create Service with Roles

curl -X POST https://auth-service-api.mahamexpo.sa/api/v1/services \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer admin-jwt-token" \
  -d '{
    "name": "expo-app",
    "display_name": "Expo Application",
    "description": "Exhibition management service",
    "roles": ["admin", "organizer"],
    "webhook_url": "http://expo-api:8000/webhook"
  }'

متغيرات البيئة

Environment Variables

جميع المتغيرات المطلوبة والاختيارية لتشغيل خدمة المصادقة

Required - مطلوبة

يجب تعيينها

APP_KEY مفتاح التشفير الرئيسي للتطبيق php artisan key:generate --show required

DB_PASSWORD كلمة سر قاعدة البيانات MySQL required

JWT_SECRET المفتاح السري لتوقيع JWT tokens openssl rand -hex 32 required

Optional - اختيارية

لها قيم افتراضية

Application & Database

APP_NAME Maham Auth Service اسم التطبيق optional

APP_ENV production بيئة التشغيل optional

APP_DEBUG false وضع التصحيح optional

APP_URL https://auth-service-api.mahamexpo.sa رابط التطبيق الرئيسي optional

APP_LOCALE ar اللغة الافتراضية optional

DB_CONNECTION mysql نوع قاعدة البيانات optional

DB_HOST auth-mysql مضيف قاعدة البيانات optional

DB_PORT 3306 منفذ قاعدة البيانات optional

DB_DATABASE auth_service اسم قاعدة البيانات optional

DB_USERNAME auth_user مستخدم قاعدة البيانات optional

Redis & Cache & Queue

REDIS_HOST auth-redis مضيف Redis optional

REDIS_PORT 6379 منفذ Redis optional

REDIS_PASSWORD (empty) كلمة سر Redis optional

CACHE_STORE redis محرك التخزين المؤقت optional

CACHE_PREFIX auth_ بادئة مفاتيح الكاش optional

QUEUE_CONNECTION redis محرك قائمة المهام optional

SESSION_DRIVER redis محرك الجلسات optional

SESSION_LIFETIME 120 عمر الجلسة (دقائق) optional

JWT & Security

JWT_TTL 60 عمر التوكن (دقائق) optional

JWT_REFRESH_TTL 20160 عمر تجديد التوكن (دقائق = 14 يوم) optional

JWT_ALGO HS256 خوارزمية التشفير optional

JWT_BLACKLIST_ENABLED true تفعيل القائمة السوداء للتوكنات optional

TRUSTED_SERVICE_IPS 172.0.0.0/8 عناوين IP الموثوقة للخدمات optional

RATE_LIMIT_PER_MINUTE 60 حد الطلبات في الدقيقة optional

BCRYPT_ROUNDS 12 جولات تشفير كلمات المرور optional

Logging & Mail

LOG_CHANNEL stack قناة التسجيل optional

LOG_LEVEL warning مستوى التسجيل optional

MAIL_MAILER log محرك البريد (log, smtp, mailgun) optional

MAIL_HOST (empty) مضيف SMTP optional

MAIL_PORT 587 منفذ SMTP optional

MAIL_USERNAME (empty) مستخدم SMTP optional

MAIL_PASSWORD (empty) كلمة سر SMTP optional

MAIL_ENCRYPTION tls تشفير البريد optional

MAIL_FROM_ADDRESS noreply@mahamexpo.sa عنوان المرسل optional

FILESYSTEM_DISK local نظام تخزين الملفات optional

خدمة المصادقة
المركزية

الميزات الرئيسية

JWT Authentication

Roles & Permissions

Service-to-Service

Service Roles

Audit Trail

Redis Caching

المصادقة

Request Body

Response 201

Request Body

Response 200

تسجيل الدخول بالجوال + رمز OTP

إدارة المستخدمين

الأدوار والصلاحيات

Roles

Permissions

إدارة الخدمات

Request Body

Response 201

إدارة الخدمات - CRUD

Service-to-Service (S2S)

البدء السريع

البنية التقنية

مسار المصادقة

تواصل الخدمات (S2S)

متغيرات البيئة

Required - مطلوبة

Optional - اختيارية

Application & Database

Redis & Cache & Queue

JWT & Security

Logging & Mail

خدمة المصادقة المركزية

الميزات الرئيسية

JWT Authentication

Roles & Permissions

Service-to-Service

Service Roles

Audit Trail

Redis Caching

المصادقة

Request Body

Response 201

Request Body

Response 200

تسجيل الدخول بالجوال + رمز OTP

إدارة المستخدمين

الأدوار والصلاحيات

Roles

Permissions

إدارة الخدمات

Request Body

Response 201

إدارة الخدمات - CRUD

Service-to-Service (S2S)

البدء السريع

البنية التقنية

مسار المصادقة

تواصل الخدمات (S2S)

متغيرات البيئة

Required - مطلوبة

Optional - اختيارية

Application & Database

Redis & Cache & Queue

JWT & Security

Logging & Mail

خدمة المصادقة
المركزية