Admin API

الـ Admin Endpoints تتطلب Bearer Token مع الصلاحية المناسبة. كل الـ Endpoints محددة النطاق بالمستفيد المُعرَّف في Header الـ X-Tenant-ID.

اصطلاح الصلاحيات: resource:read تمنح صلاحية العرض والجلب. resource:write تمنح صلاحية الإنشاء والتحديث والحذف.

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

الأدوار

الأدوار هي مجموعات مُسمّاة من الصلاحيات تُسنَد للمستخدمين. النظام يأتي بأدوار مدمجة (admin، user) لا يمكن حذفها.

GET /api/v1/roles

الصلاحية: role:read

عرض كل الأدوار في المستفيد.

curl "https://api.ithbat.io/api/v1/roles" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "roles": [
      {
        "id": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "Support Engineer",
        "description": "Read access to users and audit logs",
        "permissions": ["user:read", "audit:read"],
        "isSystem": false,
        "createdAt": "2026-01-15T10:00:00Z",
        "updatedAt": "2026-01-15T10:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/roles/{id}

الصلاحية: role:read

جلب دور واحد بالـ ID.

GET /api/v1/roles/permissions

الصلاحية: role:read

جلب قائمة بكل الصلاحيات المتاحة التي يمكن إسنادها للأدوار.

curl "https://api.ithbat.io/api/v1/roles/permissions" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "permissions": [
      "user:read", "user:write", "user:delete",
      "role:read", "role:write", "role:delete",
      "group:read", "group:write",
      "organization:read", "organization:write",
      "invitation:read", "invitation:write",
      "webhook:read", "webhook:write",
      "settings:read", "settings:write",
      "audit:read",
      "billing:read", "billing:write",
      "tenant:read", "tenant:write",
      "scim:read", "scim:write",
      "directory:read", "directory:write",
      "oauth:read", "oauth:write",
      "policy:read", "policy:write",
      "workflow:read", "workflow:write",
      "email_template:read", "email_template:write",
      "permission:read", "permission:write",
      "log:read",
      "analytics:read"
    ]
  }
}

POST /api/v1/roles

الصلاحية: role:write

إنشاء دور جديد.

Request Body

Field	Type	Required	الوصف
`name`	string	Yes	اسم الدور (فريد داخل المستفيد)
`description`	string	No	وصف مقروء
`permissions`	string[]	No	الصلاحيات الأولية

curl -X POST "https://api.ithbat.io/api/v1/roles" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Engineer",
    "description": "Read access to users and audit logs",
    "permissions": ["user:read", "audit:read"]
  }'

Response 201 — يرجع RoleResponse المُنشأ.

PUT /api/v1/roles/{id}

الصلاحية: role:write

تحديث اسم الدور أو وصفه أو صلاحياته. أدوار النظام لا يمكن تعديلها.

Request Body — كل الحقول اختيارية:

Field	Type	الوصف
`name`	string	اسم الدور الجديد
`description`	string	الوصف الجديد
`permissions`	string[]	يستبدل قائمة الصلاحيات بالكامل

DELETE /api/v1/roles/{id}

الصلاحية: role:write

حذف دور مخصص. أدوار النظام لا يمكن حذفها. المستخدمون الذين يملكون هذا الدور فقط يفقدون تلك الصلاحيات فورا.

المجموعات

المجموعات هي تجمعات من المستخدمين. أسند أدوارا للمجموعات لتطبيق الصلاحيات على كل الأعضاء دفعة واحدة.

GET /api/v1/groups

الصلاحية: group:read

عرض كل المجموعات في المستفيد.

curl "https://api.ithbat.io/api/v1/groups?page=1&limit=25" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "g1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "Engineering",
        "description": "Engineering department",
        "parentId": null,
        "memberCount": 12,
        "roleCount": 2,
        "createdAt": "2025-10-01T00:00:00Z",
        "updatedAt": "2026-01-20T00:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/groups/{id}

الصلاحية: group:read

جلب مجموعة مع قوائم الأعضاء والأدوار الكاملة.

GET /api/v1/groups/{id}/members

الصلاحية: group:read

عرض أعضاء المجموعة.

Response 200

{
  "success": true,
  "data": {
    "members": [
      { "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "joinedAt": "2025-10-05T00:00:00Z" }
    ]
  }
}

GET /api/v1/groups/{id}/roles

الصلاحية: group:read

عرض الأدوار المُسنَدة للمجموعة.

POST /api/v1/groups

الصلاحية: group:write

إنشاء مجموعة جديدة.

Request Body

Field	Type	Required	الوصف
`name`	string	Yes	اسم المجموعة (فريد داخل المستفيد)
`description`	string	No	وصف المجموعة
`parentId`	string	No	ID المجموعة الأم (للمجموعات المتداخلة)

curl -X POST "https://api.ithbat.io/api/v1/groups" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Team",
    "description": "Backend engineers",
    "parentId": "g1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Response 201 — يرجع GroupResponse المُنشأ.

PUT /api/v1/groups/{id}

الصلاحية: group:write

تحديث اسم المجموعة أو وصفها أو المجموعة الأم.

DELETE /api/v1/groups/{id}

الصلاحية: group:write

حذف مجموعة. الأعضاء لا يُحذفون — لكن يفقدون أي صلاحيات موروثة عبر هذه المجموعة.

POST /api/v1/groups/{id}/members

الصلاحية: group:write

إضافة مستخدم للمجموعة.

Request Body

Field	Type	Required	الوصف
`userId`	string	Yes	UUID المستخدم المراد إضافته

DELETE /api/v1/groups/{id}/members/{uid}

الصلاحية: group:write

إزالة مستخدم من المجموعة.

POST /api/v1/groups/{id}/roles

الصلاحية: group:write

إسناد دور للمجموعة. كل أعضاء المجموعة يرثون صلاحيات الدور.

Request Body

Field	Type	Required	الوصف
`roleId`	string	Yes	UUID الدور المراد إسناده

DELETE /api/v1/groups/{id}/roles/{rid}

الصلاحية: group:write

إزالة دور من المجموعة.

المؤسسات

المؤسسات تمثل الشركات أو الأقسام أو الكيانات الفرعية الخارجية ضمن المستفيد. الأعضاء يمكنهم الانتماء لمؤسسات متعددة بأدوار مختلفة.

GET /api/v1/organizations

الصلاحية: organization:read

عرض كل المؤسسات في المستفيد.

GET /api/v1/organizations/{id}

الصلاحية: organization:read

جلب مؤسسة بالـ ID.

GET /api/v1/organizations/{id}/members

الصلاحية: organization:read

عرض أعضاء المؤسسة.

POST /api/v1/organizations

الصلاحية: organization:write

إنشاء مؤسسة جديدة.

Request Body

Field	Type	Required	الوصف
`name`	string	Yes	اسم المؤسسة
`description`	string	No	الوصف
`domain`	string	No	نطاق البريد الإلكتروني المرتبط بالمؤسسة

curl -X POST "https://api.ithbat.io/api/v1/organizations" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme MENA",
    "description": "Middle East and Africa division",
    "domain": "acme-mena.com"
  }'

PUT /api/v1/organizations/{id}

الصلاحية: organization:write

تحديث مؤسسة.

DELETE /api/v1/organizations/{id}

الصلاحية: organization:write

حذف مؤسسة.

POST /api/v1/organizations/{id}/members

الصلاحية: organization:write

إضافة مستخدم لمؤسسة.

Request Body

Field	Type	Required	الوصف
`userId`	string	Yes	UUID المستخدم المراد إضافته

DELETE /api/v1/organizations/{id}/members/{userId}

الصلاحية: organization:write

إزالة مستخدم من مؤسسة.

PUT /api/v1/organizations/{id}/members/{userId}/roles

الصلاحية: organization:write

تحديث الأدوار التي يحملها مستخدم ضمن مؤسسة.

الدعوات

دعوة المستخدمين عبر البريد الإلكتروني. يتلقون رابط لإعداد حسابهم بكلمة مرور، ويحصلون تلقائيا على الأدوار والمجموعات المحددة عند التسجيل.

GET /api/v1/invitations

الصلاحية: invitation:read

عرض الدعوات مع إمكانية الـ Filtering.

Query Parameters

Parameter	Type	الوصف
`page`	int	رقم الصفحة
`limit`	int	عدد النتائج في الصفحة
`status`	string	Filter: `pending`، `accepted`، `expired`، `revoked`
`search`	string	بحث حسب البريد الإلكتروني

Response 200

{
  "success": true,
  "data": {
    "invitations": [
      {
        "id": "inv_abc123",
        "email": "[email protected]",
        "roles": ["r1b2c3d4-e5f6-7890-abcd-ef1234567890"],
        "groups": [],
        "invitedBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "invitedByName": "Alice Smith",
        "expiryDays": 7,
        "sentDate": "2026-02-20T10:00:00Z",
        "expiresAt": "2026-02-27T10:00:00Z",
        "status": "pending",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "createdAt": "2026-02-20T10:00:00Z",
        "updatedAt": "2026-02-20T10:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/invitations/{id}

الصلاحية: invitation:read

جلب دعوة واحدة بالـ ID.

POST /api/v1/invitations

الصلاحية: invitation:write

إرسال بريد دعوة لمستخدم واحد.

Request Body

Field	Type	Required	الوصف
`email`	string	Yes	البريد الإلكتروني للمستلم
`roles`	string[]	Yes	Role IDs المُسنَدة عند التسجيل (حد أدنى 1)
`groups`	string[]	No	Group IDs لإضافة المستخدم إليها
`firstName`	string	No	تعبئة مسبقة للاسم الأول
`familyName`	string	No	تعبئة مسبقة لاسم العائلة
`message`	string	No	رسالة مخصصة تُضمَّن في البريد
`expiryDays`	integer	No	أيام حتى انتهاء صلاحية الدعوة (الافتراضي: 7)

curl -X POST "https://api.ithbat.io/api/v1/invitations" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "roles": ["r1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "groups": ["g1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "message": "Welcome to the Acme platform!",
    "expiryDays": 7
  }'

Response 201 — يرجع InvitationResponse المُنشأ.

POST /api/v1/invitations/bulk

الصلاحية: invitation:write

إرسال دعوات لعدة عناوين بريد إلكتروني دفعة واحدة.

Request Body

Field	Type	Required	الوصف
`emails`	string[]	Yes	قائمة عناوين البريد الإلكتروني (حد أدنى 1)
`roles`	string[]	Yes	Role IDs لكل المدعوين
`groups`	string[]	No	Group IDs لكل المدعوين
`message`	string	No	رسالة مخصصة
`expiryDays`	integer	No	أيام حتى انتهاء الصلاحية

Response 200

{
  "success": true,
  "data": {
    "total": 5,
    "sent": 4,
    "failed": 1,
    "errors": [
      { "email": "[email protected]", "error": "User already exists" }
    ]
  }
}

POST /api/v1/invitations/{id}/resend

الصلاحية: invitation:write

إعادة إرسال بريد الدعوة. يمكن اختياريا تمديد فترة الصلاحية.

Request Body

Field	Type	Required	الوصف
`expiryDays`	integer	No	مدة صلاحية جديدة من الآن

POST /api/v1/invitations/{id}/revoke

الصلاحية: invitation:write

إبطال دعوة معلّقة بحيث لا يمكن قبولها.

DELETE /api/v1/invitations/{id}

الصلاحية: invitation:write

حذف سجل دعوة.

إخطارات آلية

الـ إخطارات آلية تُبلّغ أنظمتكم بالأحداث لحظيا عبر HTTP POST. Ithbat يوقّع كل Payload بتوقيع HMAC-SHA256 باستخدام الـ مفتاح توقيع الإخطار.

GET /api/v1/webhooks

الصلاحية: webhook:read

عرض كل الـ إخطارات آلية للمستفيد.

Response 200

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "wh_abc123",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "User Sync",
        "url": "https://app.acme.com/ithbat-webhooks",
        "secret": "whsec_...",
        "events": ["user.created", "user.suspended", "user.deleted"],
        "isActive": true,
        "createdAt": "2026-01-10T00:00:00Z",
        "updatedAt": "2026-01-10T00:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/webhooks/{id}

الصلاحية: webhook:read

جلب إخطار آلي بالـ ID.

GET /api/v1/webhooks/logs

الصلاحية: webhook:read

جلب Delivery Logs لكل الـ إخطارات آلية.

Response 200

{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": "del_abc123",
        "webhookId": "wh_abc123",
        "event": "user.created",
        "payload": { "userId": "a1b2..." },
        "statusCode": 200,
        "response": "OK",
        "attempts": 1,
        "lastAttemptAt": "2026-02-24T09:15:00Z",
        "status": "success",
        "createdAt": "2026-02-24T09:15:00Z"
      }
    ],
    "total": 1
  }
}

POST /api/v1/webhooks

الصلاحية: webhook:write

إنشاء إخطار آلي جديد.

Request Body

Field	Type	Required	الوصف
`name`	string	Yes	اسم وصفي
`url`	string	Yes	HTTPS Endpoint URL
`events`	string[]	Yes	Event Types للاشتراك فيها

Supported Event Types

Event	Trigger
`user.created`	إنشاء حساب مستخدم
`user.updated`	تحديث ملف مستخدم شخصي
`user.suspended`	إيقاف مستخدم
`user.reactivated`	إعادة تفعيل مستخدم موقوف
`user.deleted`	حذف مستخدم
`user.login`	تسجيل دخول مستخدم
`user.mfa_enabled`	تفعيل MFA على حساب مستخدم
`invitation.sent`	إرسال دعوة
`invitation.accepted`	قبول دعوة
`group.member_added`	إضافة مستخدم لمجموعة
`group.member_removed`	إزالة مستخدم من مجموعة
`tenant.settings_updated`	تعديل إعدادات المستفيد

curl -X POST "https://api.ithbat.io/api/v1/webhooks" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Sync",
    "url": "https://app.acme.com/ithbat-webhooks",
    "events": ["user.created", "user.deleted"]
  }'

Response 201 — يرجع إخطار آليResponse متضمنا الـ secret المُولَّد. احفظ الـ Secret فورا — يُعرَض مرة واحدة فقط عند الإنشاء.

PUT /api/v1/webhooks/{id}

الصلاحية: webhook:write

تحديث اسم الـ إخطار آلي أو الـ URL أو الـ Events أو حالة التفعيل.

Request Body

Field	Type	Required	الوصف
`name`	string	Yes	اسم وصفي
`url`	string	Yes	HTTPS Endpoint URL
`events`	string[]	Yes	Event Types (يستبدل القائمة الحالية)
`isActive`	boolean	Yes	تفعيل أو تعطيل الـ إخطار آلي

DELETE /api/v1/webhooks/{id}

الصلاحية: webhook:write

حذف إخطار آلي وكل الـ Delivery Logs المرتبطة به.

POST /api/v1/webhooks/{id}/regenerate-secret

الصلاحية: webhook:write

تدوير الـ Signing Secret للـ إخطار آلي. كل الـ Deliveries اللاحقة تستخدم الـ Secret الجديد.

Response 200

{
  "success": true,
  "data": {
    "secret": "whsec_new_value..."
  }
}

POST /api/v1/webhooks/{id}/test

الصلاحية: webhook:write

إرسال Test Event لـ نقطة استلام الإخطارات للتحقق من الاتصال.

Request Body

Field	Type	Required	الوصف
`event`	string	Yes	Event Type المراد محاكاته
`payload`	object	No	Payload مخصص للـ Test Delivery

Response 200

{
  "success": true,
  "data": {
    "success": true,
    "statusCode": 200,
    "response": "OK"
  }
}

POST /api/v1/webhooks/logs/{logId}/retry

الصلاحية: webhook:write

إعادة محاولة تسليم الإخطار فاشل.

الإعدادات

GET /api/v1/tenant/settings

الصلاحية: settings:read

جلب كل إعدادات المستفيد الحالي.

GET /api/v1/tenant/password-policy

الصلاحية: settings:read

جلب Password Policy الخاصة بالمستفيد.

Response 200

{
  "success": true,
  "data": {
    "minLength": 8,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSymbols": false,
    "maxAge": 90,
    "preventReuse": 5,
    "maxFailedAttempts": 10,
    "lockoutDuration": 30
  }
}