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

مصادقة JWT، نظام صلاحيات RBAC، وتواصل بين الخدمات

مصادقة JWT

توكنات آمنة مع تجديد وحظر

صلاحيات RBAC

أدوار وصلاحيات مع تسلسل هرمي

متعدد اللغات

عربي وإنجليزي عبر Accept-Language

Base URL

http://auth-service-api.mahamexpo.sa/api

Health CheckGET /health

{
  "status": "ok",
  "service": "auth-service",
  "version": "1.0.0",
  "timestamp": "2026-05-27T17:45:38.485225Z"
}

البدء السريع

اتبع هذه الخطوات للبدء باستخدام API

سجل حساب جديد

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

سجل الدخول واحصل على التوكن

curl -X POST http://auth-service-api.mahamexpo.sa/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"identifier":"ahmed@example.com","password":"Password123"}'

استخدم التوكن للطلبات المحمية

curl -X GET http://auth-service-api.mahamexpo.sa/api/auth/me \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

الهيدرات المطلوبة

الهيدر	القيمة	مطلوب	الوصف
`Content-Type`	`application/json`	✓	نوع المحتوى المرسل
`Accept`	`application/json`	✓	نوع المحتوى المطلوب
`Authorization`	`Bearer {token}`	للمحمية	توكن JWT للمحمية
`Accept-Language`	`ar` \| `en`	اختياري	لغة الردود

المصادقة

تستخدم الـ API مصادقة JWT.

طلبات المستخدم (JWT)

Authorization: Bearer eyJ0eXAiOiJKV1Qi...

تواصل بين الخدمات

Internal Docker Network (no auth needed)

معلومات التوكن

مدة الصلاحية: 480 دقيقة

فترة التجديد: 480 دقيقة

الخوارزمية: HS256

تنبيهات مهمة

• عند تسجيل الخروج يتم حظر التوكن
• استخدم /auth/refresh لتجديد التوكن
• التوكن القديم يصبح غير صالح بعد التجديد

صيغة الردود

رد ناجح2xx

{
  "success": true,
  "message": "Operation successful",
  "data": { ... }
}

رد خطأ4xx/5xx

{
  "success": false,
  "message": "Error message",
  "code": "error_code",
  "errors": { ... }
}

الحقل	النوع	الوصف
`success`	boolean	حالة العملية
`message`	string	رسالة توضيحية
`data`	object\|array	البيانات
`code`	string	رمز الخطأ
`errors`	object	أخطاء التحقق

POST /auth/register تسجيل مستخدم جديد عام

الحقل	النوع	مطلوب	القواعد
`name`	string	✓	max:255
`email`	string	✓	بريد صالح، فريد
`password`	string	✓	8 أحرف+، كبير وصغير وأرقام
`password_confirmation`	string	✓	يطابق كلمة المرور
`phone`	string	—	max:20

Request

{
  "name": "Ahmed",
  "email": "ahmed@example.com",
  "password": "Password123",
  "password_confirmation": "Password123",
  "phone": "0501234567"
}

Response201

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "user": { ... },
    "token": "eyJ0eXAi..."
  }
}

POST /auth/login تسجيل الدخول عام

الحقل	النوع	مطلوب	القواعد
`identifier`	string	✓	البريد أو رقم الجوال
`password`	string	✓	كلمة المرور

Request

{
  "identifier": "ahmed@example.com",
  "password": "Password123"
}

Response200

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": { ... },
    "token": "eyJ0eXAi...",
    "token_type": "bearer",
    "expires_in": 3600
  }
}

📱 تسجيل الدخول عبر OTP

تسجيل الدخول أو إنشاء حساب جديد عبر رقم الجوال و رمز التحقق — مزود Authentica

التدفق الكامل:

أرسل رقم الجوال → يصلك رمز OTP (user_type اختياري)
أرسل الرمز للتحقق → موجود = توكن، جديد = registration_token
(مستخدمين جدد) أكمل البيانات + حدد نوع الحساب user_type

🔌 المزود: Authentica — SMS + WhatsApp مع فولباك

⚠️ وضع الاختبار: أي رمز OTP مقبول (لا يُرسل SMS فعلي)

POST /auth/otp/send إرسال رمز التحقق عام

الحقل	النوع	مطلوب	القواعد
`phone`	string	✓	رقم الجوال
`user_type`	string	—	اختياري — يُكتشف تلقائياً
`channel`	string	—	sms \| whatsapp

Request

{
  "phone": "+966567891234"
}

Response200

{
  "success": true,
  "message": "تم إرسال رمز التحقق",
  "data": {
    "is_new_user": false,
    "user_type": "merchant"
  }
}

أمثلة الأخطاء المحتملة

تجاوز حد الإرسال429

{
  "success": false,
  "message": "تم تجاوز الحد الأقصى لمحاولات الإرسال",
  "error_code": "otp_max_attempts_exceeded"
}

فشل الإرسال422

{
  "success": false,
  "message": "فشل إرسال رمز التحقق",
  "error_code": "otp_send_failed"
}

بيانات غير صحيحة400

{
  "success": false,
  "message": "فشل التحقق من البيانات",
  "error_code": "validation_failed",
  "errors": {
    "phone": ["حقل الهاتف مطلوب"]
  }
}

الحساب محظور403

{
  "success": false,
  "message": "حسابك محظور. تواصل مع الدعم",
  "error_code": "user_blocked"
}

POST /auth/otp/verify تحقق من الرمز عام

الحقل	النوع	مطلوب	القواعد
`phone`	string	✓	نفس رقم الإرسال
`code`	string	✓	رمز التحقق
`user_type`	string	—	اختياري — يُكتشف تلقائياً

إذا كان المستخدم موجود → يرجع token. إذا جديد → يرجع registration_token.

Request

{
  "phone": "+966567891234",
  "code": "123456"
}

رد — مستخدم موجود200

{
  "success": true,
  "message": "تم تسجيل الدخول بنجاح",
  "data": {
    "is_new_user": false,
    "user": { ... },
    "token": "eyJ0eXAi...",
    "token_type": "bearer",
    "expires_in": 3600
  }
}

رد — مستخدم جديد200

{
  "success": true,
  "message": "تم التحقق — أكمل بياناتك للتسجيل",
  "data": {
    "is_new_user": true,
    "registration_token": "xPbaVXHRV5zXi4bBJx92Q..."
  }
}

أمثلة الأخطاء المحتملة

رمز خاطئ401

{
  "success": false,
  "message": "رمز التحقق غير صحيح",
  "error_code": "otp_invalid"
}

رمز منتهي401

{
  "success": false,
  "message": "رمز التحقق منتهي الصلاحية",
  "error_code": "otp_expired"
}

POST /auth/otp/complete-registration إكمال التسجيل بعد OTP عام

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

الحقل	النوع	مطلوب	القواعد
`registration_token`	string	✓	التوكن من verify
`name`	string	✓	الاسم الكامل
`user_type`	string	✓	merchant \| investor \| sponsor \| user
`email`	string	—	بريد إلكتروني
`business_name`	string	—	اسم المؤسسة
`business_type`	string	—	نوع النشاط
`region`	string	—	المنطقة

Request

{
  "registration_token": "xPbaVXHRV5zXi4bBJx92Q...",
  "name": "أحمد محمد",
  "user_type": "merchant",
  "email": "ahmed@example.com",
  "business_name": "مؤسسة النجاح التجارية"
}

Response201

{
  "success": true,
  "message": "تم التسجيل بنجاح",
  "data": {
    "user": { ... },
    "token": "eyJ0eXAi...",
    "token_type": "bearer",
    "expires_in": 3600
  }
}

أمثلة الأخطاء المحتملة

توكن غير صالح401

{
  "success": false,
  "message": "رمز التسجيل غير صالح أو منتهي",
  "error_code": "otp_expired"
}

بريد مكرر400

{
  "success": false,
  "error_code": "validation_failed",
  "errors": {
    "email": ["البريد مستخدم"]
  }
}

نوع ممنوع400

{
  "success": false,
  "error_code": "validation_failed",
  "errors": {
    "user_type": ["القيمة المختارة غير صالحة"]
  }
}

📱 إدارة OTP

إدارة المزودين والرصيد والإحصائيات — يحتاج أدمن

GET /admin/otp/balance رصيد المزود النشط Admin

يرجع رصيد مزود OTP النشط حالياً

Response200

{
  "success": true,
  "data": {
    "provider": "authentica",
    "balance": "100.00"
  }
}

GET /admin/otp/providers حالة المزودين Admin

يرجع حالة كل المزودين

Response200

{
  "success": true,
  "data": {
    "active_provider": "authentica",
    "test_mode": true,
    "providers": {
      "authentica": { "configured": true, "active": true },
      "twilio": { "configured": false, "active": false }
    }
  }
}

GET /admin/otp/stats إحصائيات OTP Admin

إحصائيات OTP اليوم والأسبوع والشهر

Response200

{
  "success": true,
  "data": {
    "today": { "otp_sent": 15, "otp_logins": 8, "otp_registrations": 3 },
    "this_week": { ... },
    "this_month": { ... },
    "active_provider": "authentica",
    "balance": { "balance": "99.00" }
  }
}

POST /auth/logout تسجيل الخروج Auth

لا يحتاج حقول. يتم حظر التوكن الحالي.

Response200

{
  "success": true,
  "message": "Logout successful"
}

GET /auth/me بيانات المستخدم الحالي Auth

لا يحتاج حقول.

Response200

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-...",
    "name": "Ahmed",
    "email": "ahmed@example.com",
    "phone": "0501234567",
    "status": "active",
    "roles": ["user"],
    "permissions": ["users.view"]
  }
}

POST /auth/refresh تجديد التوكن Auth

لا يحتاج حقول.

Response200

{
  "success": true,
  "data": {
    "token": "eyJ0eXAi...",
    "token_type": "bearer",
    "expires_in": 28800
  }
}

POST /auth/forgot-password طلب إعادة تعيين عام

الحقل	النوع	مطلوب	القواعد
`email`	string	✓	بريد صالح، مسجل

ملاحظة: التوكن يُرجع فقط في بيئة التطوير

POST /auth/reset-password إعادة تعيين كلمة المرور عام

الحقل	النوع	مطلوب	القواعد
`email`	string	✓	بريد صالح
`token`	string	✓	رمز إعادة التعيين
`password`	string	✓	8 أحرف+
`password_confirmation`	string	✓	يطابق كلمة المرور

POST /auth/change-password تغيير كلمة المرور Auth

الحقل	النوع	مطلوب	القواعد
`current_password`	string	✓	كلمة المرور الحالية
`password`	string	✓	8+، مختلفة عن الحالية
`password_confirmation`	string	✓	يطابق كلمة المرور

PUT /auth/profile تحديث الملف الشخصي Auth

الحقل	النوع	مطلوب	القواعد
`name`	string	—	max:255
`email`	string	—	بريد صالح، فريد
`phone`	string	—	max:20

تنبيه: عند تغيير البريد سيتم إلغاء التحقق

POST /auth/email/send-verification إرسال كود التحقق Auth

لا يحتاج حقول.

ملاحظة: الكود يُرجع فقط في بيئة التطوير. صالح 15 دقيقة.

POST /auth/email/verify التحقق من البريد Auth

الحقل	النوع	مطلوب	القواعد
`code`	string	✓	6 أرقام

POST /auth/phone/send-otp إرسال رمز تحقق الجوال Auth

يرسل رمز OTP لتوثيق رقم جوال المستخدم المسجل دخوله.

الحقل	النوع	مطلوب	القواعد
`phone`	string	✓	رقم الجوال
`channel`	string	—	sms \| whatsapp

Request

{
  "phone": "0501234567",
  "channel": "sms"
}

Response200

{
  "success": true,
  "message": "تم إرسال رمز التحقق",
  "data": {
    "channel": "sms"
  }
}

POST /auth/phone/verify-otp تأكيد رقم الجوال Auth

الحقل	النوع	مطلوب	القواعد
`phone`	string	✓	نفس الرقم
`code`	string	✓	رمز التحقق

Request

{
  "phone": "0501234567",
  "code": "123456"
}

Response200

{
  "success": true,
  "message": "تم توثيق رقم الجوال بنجاح"
}

POST /verify-token التحقق من صلاحية التوكن Auth

الحقل	النوع	مطلوب	القواعد
`token`	string	✓	توكن JWT المراد فحصه

Request

{
  "token": "eyJ0eXAi..."
}

Response200

{
  "success": true,
  "data": {
    "valid": true,
    "user": { ... },
    "expires_at": "..."
  }
}

POST /check-permission فحص صلاحية واحدة Auth

الحقل	النوع	مطلوب	القواعد
`user_id`	string (UUID)	✓	UUID المستخدم
`permission`	string	✓	مثل: users.view

Request

{
  "user_id": "uuid-here",
  "permission": "users.view"
}

Response200

{
  "success": true,
  "data": {
    "has_permission": true,
    "user_id": "uuid",
    "permission": "users.view"
  }
}

POST /check-permissions فحص عدة صلاحيات Auth

الحقل	النوع	مطلوب	القواعد
`user_id`	string (UUID)	✓	UUID المستخدم
`permissions`	array	✓	مصفوفة الصلاحيات
`require_all`	boolean	—	الافتراضي: false

Request

{
  "user_id": "uuid-here",
  "permissions": [
    "users.view",
    "users.create"
  ],
  "require_all": false
}

Response200

{
  "success": true,
  "data": {
    "has_access": true,
    "permissions": {
      "users.view": true,
      "users.create": false
    },
    "require_all": false
  }
}

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

CRUD كامل - تتطلب صلاحيات users.*

الطريقة	المسار	الوصف	الصلاحية
GET	`/users`	قائمة المستخدمين	users.view
POST	`/users`	إنشاء مستخدم	users.create
GET	`/users/{id}`	عرض مستخدم	users.view
PUT	`/users/{id}`	تحديث مستخدم	users.update
DEL	`/users/{id}`	حذف مستخدم	users.delete

حقول إنشاء / تحديث المستخدم

الحقل	النوع	إنشاء	تحديث	القواعد
`name`	string	✓	—	max:255
`email`	string	✓	—	بريد صالح، فريد
`password`	string	✓	—	8 أحرف+
`password_confirmation`	string	✓	—	يطابق كلمة المرور
`phone`	string	—	—	max:20
`status`	string	—	—	active \| suspended \| blocked
`roles`	array	—	—	مصفوفة أسماء الأدوار

إدارة الأدوار

Method	Endpoint	الوصف	Permission
GET	`/roles`	قائمة الأدوار	roles.view
POST	`/roles`	إنشاء دور	roles.create
GET	`/roles/{id}`	عرض دور	roles.view
PUT	`/roles/{id}`	تحديث دور	roles.update
DEL	`/roles/{id}`	حذف دور	roles.delete
POST	`/roles/{id}/permissions`	مزامنة الصلاحيات	roles.update
POST	`/roles/{id}/permissions/add`	إضافة صلاحيات	roles.update
POST	`/roles/{id}/permissions/remove`	إزالة صلاحيات	roles.update

حقول إنشاء/تحديث الدور

Field	Type	Create	Update	Rules
`name`	string	✓	—	فريد، max:255
`display_name`	string	—	—	max:255
`description`	string	—	—	max:500

حقول مزامنة / إضافة / إزالة الصلاحيات

Field	Type	Required	Rules
`permissions`	array	✓	["users.view", "users.create"]

إدارة الصلاحيات

Method	Endpoint	الوصف	Permission
GET	`/permissions`	قائمة الصلاحيات	permissions.view
POST	`/permissions`	إنشاء صلاحية	permissions.create
POST	`/permissions/resource`	إنشاء مجموعة لمورد	permissions.create
GET	`/permissions/{id}`	عرض صلاحية	permissions.view
PUT	`/permissions/{id}`	تحديث صلاحية	permissions.update
DEL	`/permissions/{id}`	حذف صلاحية	permissions.delete

POST /permissions

Field	Type	Required	Rules
`name`	string	✓	فريد، مثل: reports.export
`display_name`	string	—	max:255
`description`	string	—	max:500

POST /permissions/resource

Field	Type	Required	Rules
`resource`	string	✓	اسم المورد
`actions`	array	—	الافتراضي: [view,create,update,delete]

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

Method	Endpoint	الوصف	Permission
GET	`/services`	قائمة الخدمات	services.view
POST	`/services`	إنشاء خدمة	services.create
GET	`/services/{id}`	عرض خدمة	services.view
PUT	`/services/{id}`	تحديث خدمة	services.update
DEL	`/services/{id}`	حذف خدمة	services.delete
POST	`/services/{id}/regenerate-token`	إعادة توليد التوكن	services.update

حقول إنشاء/تحديث الخدمة

Field	Type	Create	Update	Rules
`name`	string	✓	—	فريد، max:255
`base_url`	string	✓	—	URL صالح
`description`	string	—	—	max:500
`is_active`	boolean	—	—	الافتراضي: true

تواصل بين الخدمات (S2S)

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

No authentication required — internal Docker network

Method	Endpoint	الوصف
POST	`/service/verify-token`	التحقق من توكن مستخدم
POST	`/service/check-permission`	فحص صلاحية مستخدم
POST	`/service/user-info`	جلب بيانات مستخدم

حقول S2S

Endpoint	Field	Type	Required	الوصف
`/service/verify-token`	`token`	string	✓	توكن JWT
`/service/check-permission`	`user_id`	string	✓	UUID
`/service/check-permission`	`permission`	string	✓	اسم الصلاحية
`/service/user-info`	`user_id`	string	✓	UUID

رموز الحالة HTTP

الرمز	Name	الوصف
نجاح
200	OK	تمت العملية بنجاح
201	Created	تم إنشاء المورد
أخطاء العميل
400	Bad Request	خطأ في التحقق
401	Unauthorized	غير مصرح
403	Forbidden	ليس لديك صلاحية
404	Not Found	غير موجود
422	Unprocessable	لا يمكن معالجتها
429	Too Many	تجاوز حد الطلبات
أخطاء الخادم
500	Server Error	خطأ في الخادم

جدول رموز الأخطاء

شكل رد الخطأ

رد خطأ عام4xx/5xx

{
  "success": false,
  "message": "رسالة الخطأ بالعربي",
  "error_code": "error_code_string"
}

رد خطأ التحقق400

{
  "success": false,
  "message": "فشل التحقق من البيانات",
  "error_code": "validation_failed",
  "errors": {
    "phone": ["حقل الهاتف مطلوب"],
    "code": ["الرمز يجب أن يكون 4 أحرف على الأقل"]
  }
}

ملاحظة: حقل errors يظهر فقط في أخطاء التحقق

Error Code	HTTP	الوصف
🔐 OTP / SMS / WhatsApp
`otp_send_failed`	422	فشل إرسال رمز التحقق
`otp_invalid`	401	رمز التحقق غير صحيح
`otp_expired`	401	رمز التحقق منتهي الصلاحية
`otp_max_attempts_exceeded`	429	تجاوزت الحد الأقصى للمحاولات
`otp_already_sent`	429	تم إرسال رمز مسبقاً
`phone_verification_required`	403	يجب التحقق من الجوال أولاً
`phone_already_verified`	409	الجوال محقق مسبقاً
`email_verification_required`	403	يجب التحقق من البريد
`email_already_verified`	409	البريد محقق مسبقاً
🔑 Authentication
`authentication_required`	401	يجب تسجيل الدخول
`invalid_login_credentials`	401	بيانات الدخول غير صحيحة
`token_expired`	401	انتهت صلاحية التوكن
`token_invalid`	401	التوكن غير صالح
`token_blacklisted`	401	التوكن محظور
`token_not_provided`	401	لم يتم إرسال التوكن
`too_many_login_attempts`	429	محاولات دخول كثيرة
`account_locked`	403	الحساب مقفل
🛡️ Authorization / Account
`permission_denied`	403	ليس لديك صلاحية
`insufficient_permissions`	403	صلاحيات غير كافية
`user_blocked`	403	الحساب محظور
`user_suspended`	403	الحساب معلّق
`user_disabled`	403	الحساب معطّل
`user_not_verified`	403	الحساب غير موثق
`user_deleted`	404	الحساب محذوف
⚠️ Validation
`validation_failed`	400	فشل التحقق من البيانات
`invalid_phone_format`	400	صيغة الجوال غير صحيحة
`invalid_email_format`	400	صيغة البريد غير صحيحة
`missing_required_field`	400	حقل مطلوب مفقود
`invalid_input`	400	إدخال غير صالح
📦 Resources
`resource_not_found`	404	المورد غير موجود
`resource_already_exists`	409	المورد موجود مسبقاً
`user_not_found`	404	المستخدم غير موجود
`user_already_exists`	409	المستخدم موجود مسبقاً
`user_email_already_exists`	409	البريد مستخدم
`user_phone_already_exists`	409	الجوال مسجل مسبقاً
`role_not_found`	404	الدور غير موجود
🔒 Password
`password_reset_token_invalid`	401	رمز إعادة التعيين غير صالح
`password_reset_token_expired`	401	رمز إعادة التعيين منتهي
`password_same_as_old`	400	كلمة المرور مطابقة للقديمة
`password_mismatch`	400	كلمة المرور غير متطابقة
⏱️ Rate Limiting
`rate_limit_exceeded`	429	تجاوزت حد الطلبات
`rate_limit_login_exceeded`	429	محاولات دخول كثيرة
🖥️ Server / Service
`internal_server_error`	500	خطأ داخلي في السيرفر
`service_unavailable`	503	الخدمة غير متوفرة
`service_communication_failed`	502	فشل الاتصال بالخدمة
`maintenance_mode`	503	وضع الصيانة

💡 الأكواد أعلاه هي الأكثر استخداماً. يوجد 120+ كود خطأ.

حد الطلبات

النوع	الحد	الفترة
API Requests		في الدقيقة
Login Attempts	10	في الدقيقة
Service-to-Service	100	في الدقيقة

الأدوار والصلاحيات الافتراضية

super-admin

وصول كامل

admin

إدارة كاملة

supervisor

مراقبة وموافقات

investor

إدارة المساحات

merchant

طلبات إيجار وزيارة

sponsor

إدارة الرعاية

user

مستخدم عادي

المورد	الصلاحيات
Users	`users.view` `users.create` `users.update` `users.delete`
Roles	`roles.view` `roles.create` `roles.update` `roles.delete`
Permissions	`permissions.view` `permissions.create` `permissions.update` `permissions.delete`
Services	`services.view` `services.create` `services.update` `services.delete`