مرجع API

Ithbat IAM REST API يوفر وصول برمجي لكل إمكانيات المنصة — إدارة المستخدمين، تدفقات المصادقة، RBAC، المجموعات، المؤسسات، إخطارات آلية، سجلات التدقيق، وغيرها.

Base URL

كل الـ API Requests تستهدف الـ Base URL التالي:

https://api.ithbat.io/api/v1/

في حال متطلبات إقامة البيانات، تتوفر Regional Endpoints:

Region	Base URL
Global	https://api.ithbat.io/api/v1/
KSA	https://api.sa.ithbat.io/api/v1/
Egypt	https://api.eg.ithbat.io/api/v1/

استخدم الـ Regional Endpoint المطابق لإعداد إقامة البيانات الخاص بالمستفيد. الـ Region يتحدد عند إنشاء المستفيد ولا يمكن تغييره.

المصادقة

كل الـ Protected Endpoints تتطلب Bearer JWT Access Token في الـ Authorization Header:

Authorization: Bearer <access_token>

احصل على Access Token عبر POST /api/v1/auth/login. الـ Tokens تنتهي صلاحيتها بعد 3600 ثانية. استخدم POST /api/v1/auth/refresh مع الـ Refresh Token للحصول على Access Token جديد بدون إعادة المصادقة.

Tenant Context

الـ Multi-tenant Requests تتطلب معرّف المستفيد:

X-Tenant-ID: <tenant_uuid>

الـ Requests بدون X-Tenant-ID يتم تحديد نطاقها من الـ JWT الخاص بالمستخدم.

Request Format

كل الـ Request Bodies يجب أن تكون JSON مع الـ Content-Type Header المناسب:

Content-Type: application/json

مثال على Authenticated Request

curl -X GET "https://api.ithbat.io/api/v1/users/me" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json"

Response Format

كل الـ API Responses تستخدم JSON Envelope موحد:

{
  "success": true,
  "data": { },
  "message": "Operation completed"
}

الـ List Responses تتضمن بيانات الـ Pagination:

{
  "success": true,
  "data": {
    "users": [ ],
    "total": 142,
    "page": 1,
    "limit": 25,
    "totalPages": 6
  }
}

Error Format

الـ Errors ترجع JSON Envelope يتضمن Error Code قابل للقراءة آليا:

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email or password is incorrect"
  }
}

أخطاء الـ Validation تتضمن تفاصيل لكل حقل:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "must be a valid email address" },
      { "field": "password", "message": "must be at least 8 characters" }
    ]
  }
}

HTTP Status Codes

Code	المعنى
200	نجاح
201	تم إنشاء المورد
400	Bad Request — JSON غير صالح أو حقول مطلوبة مفقودة
401	Unauthorized — الـ Access Token مفقود أو غير صالح
403	Forbidden — المستخدم مصادق عليه لكن الصلاحيات غير كافية
404	Not Found — المورد غير موجود أو غير مرئي للمستفيد
409	Conflict — المورد موجود مسبقا (بريد إلكتروني أو slug مكرر)
422	Unprocessable Entity — الـ Request صالح هيكليا لكنه يخالف قواعد العمل
429	Too Many Requests — تم تجاوز الـ Rate Limit
500	Internal Server Error

Pagination

الـ List Endpoints تقبل page و limit كـ Query Parameters:

Parameter	Type	Default	Max	الوصف
page	integer	1	—	رقم الصفحة، يبدأ من 1
limit	integer	25	100	عدد النتائج في الصفحة

مثال:

curl "https://api.ithbat.io/api/v1/users?page=2&limit=50" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response:

{
  "success": true,
  "data": {
    "users": [ ],
    "total": 142,
    "page": 2,
    "limit": 50,
    "totalPages": 3
  }
}

Rate Limiting

الـ Rate Limits مطبقة لكل API Key ولكل IP Address. معلومات الـ Limit ترجع في كل Response:

Header	الوصف
X-RateLimit-Limit	الحد الأقصى للـ Requests في الـ Window الحالية
X-RateLimit-Remaining	الـ Requests المتبقية في الـ Window الحالية
X-RateLimit-Reset	Unix Timestamp لإعادة تعيين الـ Window

عند تجاوز الحد، الـ API يرجع HTTP 429 مع Error Body:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 1740432000."
  }
}

الحدود الافتراضية:

الباقة	Requests / min
Free	60
Pro	300
Enterprise	1,200
Sandbox	30

Versioning

الإصدار الحالي هو v1. الإصدار جزء من الـ URL Path: /api/v1/. الـ Breaking Changes تُقدَّم في إصدار جديد (/api/v2/) مع إشعار إيقاف وفترة ترحيل لا تقل عن ستة أشهر. الإضافات غير الجذرية مثل الحقول الجديدة والـ Endpoints الجديدة قد تُضاف للإصدار الحالي بدون إشعار مسبق.

Common Error Codes

Code	الوصف
INVALID_CREDENTIALS	البريد الإلكتروني أو كلمة المرور غير صحيحة
ACCOUNT_SUSPENDED	حساب المستخدم موقوف
ACCOUNT_NOT_VERIFIED	لم يتم التحقق من البريد الإلكتروني
MFA_REQUIRED	مطلوب تحقق MFA للمتابعة
TOKEN_EXPIRED	انتهت صلاحية الـ Access Token
TOKEN_INVALID	الـ Access Token غير صالح أو تم إبطاله
TENANT_NOT_FOUND	المستفيد المحدد غير موجود
TENANT_SUSPENDED	حساب المستفيد موقوف
PERMISSION_DENIED	المستخدم لا يملك الصلاحية المطلوبة
RESOURCE_NOT_FOUND	المورد المطلوب غير موجود
DUPLICATE_EMAIL	يوجد مستخدم بهذا البريد الإلكتروني مسبقا
VALIDATION_ERROR	فشل الـ Validation لحقل واحد أو أكثر
RATE_LIMIT_EXCEEDED	عدد Requests كثير جدا في الـ Window الحالية
IP_NOT_WHITELISTED	الـ IP Address ليس ضمن القائمة المسموح بها للمستفيد