انتقل إلى المحتوى الرئيسي

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

يوفر Ithbat واجهة API ولوحة تحكم كاملة لإدارة دورة حياة المستخدم. يمكن إنشاء المستخدمين يدويًا، أو استيرادهم عبر CSV، أو تزويدهم تلقائيًا عبر SCIM، أو إنشاؤهم بالتسجيل الذاتي وJIT Provisioning عبر SAML.

حقول الملف الشخصي​

يتضمن كل حساب مستخدم الحقول التالية:

الحقلالنوعالوصف
idUUIDمعرّف فريد
emailstringالبريد الإلكتروني الأساسي، فريد داخل الـ Tenant
firstNamestringالاسم الأول
lastNamestringاسم العائلة
phonestringرقم الهاتف (اختياري)
localestringBCP 47 Language Tag، مثل en، ar
statusenumactive، suspended، pending
emailVerifiedboolهل تم التحقق من البريد الإلكتروني
externalIdstringمعرّف من نظام خارجي (مثلًا IdP User ID)
metadataobjectKey-Value Pairs لاستخدامك الخاص
createdAttimestampوقت إنشاء الحساب
lastLoginAttimestampآخر تسجيل دخول ناجح

دعوة المستخدمين​

الطريقة المُوصى بها لإضافة مستخدمين. يرسل Ithbat بريدًا إلكترونيًا برابط آمن. ينقر المستخدم الرابط، يعيّن كلمة المرور، ويُفعَّل حسابه.

عبر لوحة تحكم المسؤول​

  1. انتقل إلى المستخدمون > دعوة مستخدم.
  2. أدخل البريد الإلكتروني واختياريًا الاسم الأول واسم العائلة.
  3. اختر الأدوار للتعيين عند القبول.
  4. انقر إرسال الدعوة.

عبر الـ API​

POST /api/v1/invitations
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "roleIds": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
}

الـ Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "[email protected]",
  "status": "pending",
  "expiresAt": "2026-03-03T10:00:00Z",
  "createdAt": "2026-02-24T10:00:00Z"
}

تنتهي صلاحية الدعوات بعد 7 أيام. لإعادة إرسال دعوة منتهية:

POST /api/v1/invitations/{id}/resend
Authorization: Bearer {token}

Bulk Invitations​

أرسل حتى 50 دعوة في Request واحد:

POST /api/v1/invitations/bulk
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "invitations": [
    { "email": "[email protected]", "firstName": "User", "lastName": "One" },
    { "email": "[email protected]", "firstName": "User", "lastName": "Two" }
  ],
  "roleIds": ["7c9e6679-..."]
}

إنشاء المستخدمين مباشرة​

أنشئ مستخدمين بدون تدفق الدعوة. يُنشأ المستخدم بحالة active مع emailVerified: false ما لم يُحدَّد خلاف ذلك.

POST /api/v1/users
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+966501234567",
  "locale": "ar"
}

الـ Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "tenantId": "c2e3f4a5-...",
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+966501234567",
  "locale": "ar",
  "status": "active",
  "emailVerified": false,
  "createdAt": "2026-02-24T10:00:00Z",
  "updatedAt": "2026-02-24T10:00:00Z"
}

عرض المستخدمين​

سرد جميع المستخدمين​

GET /api/v1/users
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

يدعم Pagination عبر (page، limit) والتصفية بـ status وemail وغيرها.

جلب مستخدم واحد​

GET /api/v1/users/{id}
Authorization: Bearer {token}

جلب المستخدم الحالي (Authenticated)​

GET /api/v1/users/me
Authorization: Bearer {user_token}

تحديث المستخدمين​

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

PUT /api/v1/users/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+966501234567",
  "locale": "en"
}

تحديث الـ Metadata​

أرفق Key-Value Metadata بالمستخدم دون تعديل حقول الملف الشخصي:

PATCH /api/v1/users/{id}/metadata
Authorization: Bearer {token}
Content-Type: application/json

{
  "department": "Engineering",
  "employeeId": "EMP-1042",
  "costCenter": "CC-500"
}

إيقاف وإعادة تفعيل المستخدمين​

يمنع الإيقاف تسجيل الدخول مع الحفاظ على البيانات والـ Sessions وتعيينات الأدوار. تُبطَل جميع الـ Sessions النشطة فورًا عند الإيقاف.

إيقاف مستخدم​

POST /api/v1/users/{id}/suspend
Authorization: Bearer {token}

إعادة تفعيل مستخدم موقوف​

POST /api/v1/users/{id}/reactivate
Authorization: Bearer {token}

فتح حساب مقفل​

تُقفل الحسابات تلقائيًا بعد محاولات تسجيل دخول فاشلة متكررة (حسب الـ Password Policy). للفتح يدويًا:

POST /api/v1/users/{id}/unlock
Authorization: Bearer {token}

حذف المستخدمين​

الحذف نهائي ولا رجعة فيه. تُزال جميع الـ Sessions وتعيينات الأدوار وعضويات المجموعات والبيانات الشخصية.

DELETE /api/v1/users/{id}
Authorization: Bearer {token}

Bulk Delete​

DELETE /api/v1/users/bulk
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "userIds": [
    "3fa85f64-...",
    "7c9e6679-..."
  ]
}

CSV Import​

استورد أعدادًا كبيرة من المستخدمين من ملف CSV.

إعداد ملف CSV​

يجب أن يتضمن الملف Header Row. الأعمدة المدعومة:

email,firstName,lastName,phone,locale,externalId
[email protected],Jane,Doe,+966501234567,en,EMP-1042
[email protected],John,Smith,,ar,EMP-1043

العمود الوحيد المطلوب: email. الباقي اختياري.

الاستيراد عبر الـ API​

POST /api/v1/users/import
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: multipart/form-data

[email protected]

يُعالَج الاستيراد بشكل غير متزامن. يتضمن الـ Response الـ Job ID:

{
  "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "queued"
}

للاستعلام عن حالة الـ Job:

GET /api/v1/jobs/{jobId}/status
Authorization: Bearer {token}

CSV Export​

POST /api/v1/users/export
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "format": "csv",
  "fields": ["email", "firstName", "lastName", "status", "createdAt"]
}

يرجع Job ID. استرجع النتيجة عند الاكتمال:

GET /api/v1/jobs/{jobId}/result
Authorization: Bearer {token}

Password Policy​

إعداد متطلبات كلمات المرور للـ Tenant.

جلب السياسة الحالية​

GET /api/v1/tenant/password-policy
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

الـ Response:

{
  "minLength": 8,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireNumbers": true,
  "requireSymbols": false,
  "maxAge": 90,
  "preventReuse": 5,
  "maxLoginAttempts": 5,
  "lockoutDuration": 900
}

تحديث السياسة​

PUT /api/v1/tenant/password-policy
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "minLength": 12,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireNumbers": true,
  "requireSymbols": true,
  "maxAge": 90,
  "preventReuse": 10,
  "maxLoginAttempts": 5,
  "lockoutDuration": 1800
}
الحقلالوصف
minLengthالحد الأدنى لطول كلمة المرور (1-128)
requireUppercaseحرف كبير واحد على الأقل
requireLowercaseحرف صغير واحد على الأقل
requireNumbersرقم واحد على الأقل
requireSymbolsرمز خاص واحد على الأقل
maxAgeانتهاء صلاحية كلمة المرور بالأيام (0 = لا تنتهي)
preventReuseعدد كلمات المرور السابقة المحظور إعادة استخدامها
maxLoginAttemptsالمحاولات الفاشلة قبل القفل
lockoutDurationمدة القفل بالثواني

إدارة الـ Sessions​

عرض الـ Sessions النشطة لمستخدم​

GET /api/v1/users/{id}/sessions
Authorization: Bearer {token}

إبطال جميع الـ Sessions لمستخدم​

DELETE /api/v1/users/{id}/sessions
Authorization: Bearer {token}

Users API Reference​

MethodEndpointالصلاحية
GET/api/v1/usersuser:read
GET/api/v1/users/{id}user:read
POST/api/v1/usersuser:write
PUT/api/v1/users/{id}user:write
DELETE/api/v1/users/{id}user:delete
POST/api/v1/users/{id}/suspenduser:write
POST/api/v1/users/{id}/reactivateuser:write
POST/api/v1/users/{id}/unlockuser:write
POST/api/v1/users/bulkuser:write
DELETE/api/v1/users/bulkuser:write
POST/api/v1/users/importuser:write
POST/api/v1/users/exportuser:write
PATCH/api/v1/users/{id}/metadatauser:write
POST/api/v1/invitationsinvitation:write
POST/api/v1/invitations/bulkinvitation:write
POST/api/v1/invitations/{id}/resendinvitation:write
POST/api/v1/invitations/{id}/revokeinvitation:write

الخطوات التالية​