Users API

الـ User Endpoints تغطي فئتين:

Self-service (/users/me) — أي مستخدم مصادق عليه يدير ملفه الشخصي و Sessions.
Admin User Management (/users، /users/{id}) — تتطلب صلاحية user:read أو user:write.

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

GET /api/v1/users/me

يتطلب مصادقة.

جلب الملف الشخصي الكامل للمستخدم المصادق عليه.

curl "https://api.ithbat.io/api/v1/users/me" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "email": "[email protected]",
    "firstName": "Alice",
    "fatherName": "",
    "grandfatherName": "",
    "familyName": "Smith",
    "displayName": "Alice Smith",
    "status": "active",
    "roles": ["admin"],
    "preferences": {
      "theme": "light",
      "language": "en",
      "timezone": "UTC"
    },
    "mfaEnabled": true,
    "metadata": {},
    "externalIds": {},
    "lastLoginAt": "2026-02-24T09:15:00Z",
    "passwordChangedAt": "2026-01-10T14:00:00Z",
    "createdAt": "2025-09-01T08:00:00Z",
    "updatedAt": "2026-02-24T09:15:00Z"
  }
}

PUT /api/v1/users/me

يتطلب مصادقة.

تحديث الملف الشخصي للمستخدم المصادق عليه. كل الحقول اختيارية — فقط الحقول المُقدمة يتم تحديثها.

Request Body

Field	Type	Required	الوصف
`firstName`	string	No	الاسم الأول
`fatherName`	string	No	اسم الأب
`grandfatherName`	string	No	اسم الجد
`familyName`	string	No	اسم العائلة

curl -X PUT "https://api.ithbat.io/api/v1/users/me" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alicia",
    "familyName": "Smith-Jones"
  }'

Response 200 — يرجع UserResponse المُحدَّث (نفس هيكل GET /users/me).

GET /api/v1/users/me/identities

يتطلب مصادقة.

عرض كل الـ Social Identity Providers المرتبطة بحساب المستخدم المصادق عليه.

curl "https://api.ithbat.io/api/v1/users/me/identities" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "data": {
    "identities": [
      {
        "provider": "google",
        "providerUserId": "115789123456789",
        "email": "[email protected]",
        "linkedAt": "2025-10-15T11:00:00Z"
      }
    ]
  }
}

POST /api/v1/users/me/identities/{provider}

يتطلب مصادقة.

ربط Social Identity Provider بحساب المستخدم المصادق عليه.

Path Parameters

Parameter	Type	الوصف
`provider`	string	اسم الـ Provider: `google`، `github`، `microsoft`، `apple`

DELETE /api/v1/users/me/identities/{provider}

يتطلب مصادقة.

إلغاء ربط Social Identity Provider من حساب المستخدم. يجب أن يكون للمستخدم كلمة مرور أو Provider آخر مرتبط على الأقل قبل إلغاء الربط.

GET /api/v1/auth/sessions

يتطلب مصادقة.

عرض كل الـ Active Sessions للمستخدم المصادق عليه.

curl "https://api.ithbat.io/api/v1/auth/sessions" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "sess_abc123",
        "deviceType": "desktop",
        "deviceName": "Chrome on Windows",
        "ipAddress": "197.134.10.55",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "location": {
          "country": "SA",
          "city": "Riyadh",
          "latitude": 24.7136,
          "longitude": 46.6753
        },
        "createdAt": "2026-02-24T09:00:00Z",
        "lastActivity": "2026-02-24T09:15:00Z",
        "isCurrent": true
      }
    ],
    "total": 1
  }
}

DELETE /api/v1/auth/sessions/{id}

يتطلب مصادقة.

إبطال Session محدد بالـ ID. استخدم GET /api/v1/auth/sessions لعرض الـ Session IDs.

curl -X DELETE "https://api.ithbat.io/api/v1/auth/sessions/sess_abc123" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "message": "Session revoked"
}

DELETE /api/v1/auth/sessions

يتطلب مصادقة.

إبطال كل Sessions المستخدم المصادق عليه عدا الـ Session الحالي.

curl -X DELETE "https://api.ithbat.io/api/v1/auth/sessions" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "message": "All other sessions revoked"
}

GET /api/v1/users

الصلاحية المطلوبة: user:read

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

Query Parameters

Parameter	Type	Default	الوصف
`page`	integer	1	رقم الصفحة
`limit`	integer	25	عدد النتائج في الصفحة (الحد الأقصى 100)
`search`	string	—	Filter حسب الاسم أو البريد الإلكتروني
`status`	string	—	Filter حسب الحالة: `active`، `suspended`، `pending`
`roleId`	string	—	Filter حسب الـ Role ID

curl "https://api.ithbat.io/api/v1/users?page=1&limit=25&search=alice" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "email": "[email protected]",
        "firstName": "Alice",
        "fatherName": "",
        "grandfatherName": "",
        "familyName": "Smith",
        "displayName": "Alice Smith",
        "status": "active",
        "roles": ["admin"],
        "mfaEnabled": true,
        "lastLoginAt": "2026-02-24T09:15:00Z",
        "createdAt": "2025-09-01T08:00:00Z",
        "updatedAt": "2026-02-24T09:15:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/users/{id}

الصلاحية المطلوبة: user:read

جلب مستخدم محدد بالـ UUID.

curl "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200 — يرجع UserResponse الكامل.

Error Codes

Code	HTTP	الوصف
`RESOURCE_NOT_FOUND`	404	المستخدم غير موجود في هذا المستفيد

POST /api/v1/users

الصلاحية المطلوبة: user:write

إنشاء مستخدم جديد في المستفيد. يمكن اختياريا تخطي التحقق من البريد الإلكتروني للإنشاء البرمجي.

Request Body

Field	Type	Required	الوصف
`email`	string	Yes	البريد الإلكتروني (يجب أن يكون فريد في المستفيد)
`firstName`	string	Yes	الاسم الأول
`fatherName`	string	No	اسم الأب
`grandfatherName`	string	No	اسم الجد
`familyName`	string	Yes	اسم العائلة
`password`	string	No	كلمة المرور الأولية (يتم توليدها تلقائيا إذا لم تُحدد)
`skipEmailVerification`	boolean	No	تخطي بريد التحقق (الافتراضي: false)

curl -X POST "https://api.ithbat.io/api/v1/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Carol",
    "familyName": "Williams",
    "skipEmailVerification": true
  }'

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

Error Codes

Code	HTTP	الوصف
`DUPLICATE_EMAIL`	409	يوجد مستخدم بهذا البريد الإلكتروني مسبقا
`VALIDATION_ERROR`	400	كلمة المرور لا تستوفي متطلبات السياسة

PUT /api/v1/users/{id}

الصلاحية المطلوبة: user:write

تحديث الملف الشخصي لمستخدم بالـ ID.

Request Body

Field	Type	Required	الوصف
`firstName`	string	No	الاسم الأول
`fatherName`	string	No	اسم الأب
`grandfatherName`	string	No	اسم الجد
`familyName`	string	No	اسم العائلة

curl -X PUT "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Alicia"}'

Response 200 — يرجع UserResponse المُحدَّث.

DELETE /api/v1/users/{id}

الصلاحية المطلوبة: user:write

حذف مستخدم نهائيا وإبطال كل الـ Active Sessions. هذا الإجراء لا يمكن التراجع عنه.

curl -X DELETE "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User deleted"
}

POST /api/v1/users/{id}/suspend

الصلاحية المطلوبة: user:write

إيقاف حساب مستخدم. المستخدمون الموقوفون لا يستطيعون تسجيل الدخول، ويتم إبطال كل الـ Active Sessions.

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/suspend" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User suspended"
}

POST /api/v1/users/{id}/reactivate

الصلاحية المطلوبة: user:write

إعادة تفعيل حساب مستخدم سبق إيقافه.

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reactivate" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User reactivated"
}

POST /api/v1/users/{id}/unlock

الصلاحية المطلوبة: user:write

فك قفل حساب مستخدم تم قفله بعد محاولات تسجيل دخول فاشلة.

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/unlock" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User account unlocked"
}

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

الصلاحية المطلوبة: role:write

إسناد دور لمستخدم.

Request Body

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

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/roles" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"roleId": "r1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Response 200

{
  "success": true,
  "message": "Role assigned"
}

DELETE /api/v1/users/{id}/roles/{roleId}

الصلاحية المطلوبة: role:write

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

curl -X DELETE "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/roles/r1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "Role removed"
}

GET /api/v1/users/{id}/permissions

الصلاحية المطلوبة: user:read

جلب مجموعة الصلاحيات المُحلَّلة لمستخدم، شاملة كل الصلاحيات من كل الأدوار المُسنَدة.

curl "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/permissions" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "permissions": [
      "user:read",
      "user:write",
      "role:read",
      "role:write",
      "group:read",
      "group:write",
      "audit:read"
    ]
  }
}

POST /api/v1/users/bulk

الصلاحية المطلوبة: user:write

إنشاء عدة مستخدمين في Request واحد. الحد الأقصى 1000 مستخدم لكل Batch.

Request Body

Field	Type	Required	الوصف
`users`	array	Yes	Array من `CreateUserRequest` Objects (حد أدنى 1، حد أقصى 1000)

curl -X POST "https://api.ithbat.io/api/v1/users/bulk" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      { "email": "[email protected]", "firstName": "User", "familyName": "One" },
      { "email": "[email protected]", "firstName": "User", "familyName": "Two" }
    ]
  }'

Response 200

{
  "success": true,
  "data": {
    "successful": 2,
    "failed": 0,
    "users": [ ]
  }
}

الـ Partial Failures ترجع نفس الهيكل مع failed > 0 و errors Array:

{
  "success": true,
  "data": {
    "successful": 1,
    "failed": 1,
    "errors": [
      {
        "index": 1,
        "email": "[email protected]",
        "error": "A user with this email already exists",
        "code": "DUPLICATE_EMAIL"
      }
    ],
    "users": [ ]
  }
}

PATCH /api/v1/users/{id}/metadata

الصلاحية المطلوبة: user:write

تعيين أو دمج Metadata مخصصة على مستخدم. مفيد لتخزين Attributes خاصة بالتطبيق.

Request Body

Field	Type	Required	الوصف
`metadata`	object	Yes	أزواج Key-Value (القيم يمكن أن تكون أي JSON Type)

curl -X PATCH "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/metadata" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "department": "Engineering",
      "employeeId": "EMP-0042",
      "costCenter": "CC-101"
    }
  }'

Response 200 — يرجع UserResponse المُحدَّث.

GET /api/v1/users/me​

PUT /api/v1/users/me​

GET /api/v1/users/me/identities​

POST /api/v1/users/me/identities/{provider}​

DELETE /api/v1/users/me/identities/{provider}​

GET /api/v1/auth/sessions​

DELETE /api/v1/auth/sessions/{id}​

DELETE /api/v1/auth/sessions​

GET /api/v1/users​

GET /api/v1/users/{id}​

POST /api/v1/users​

PUT /api/v1/users/{id}​

DELETE /api/v1/users/{id}​

POST /api/v1/users/{id}/suspend​

POST /api/v1/users/{id}/reactivate​

POST /api/v1/users/{id}/unlock​

POST /api/v1/users/{id}/roles​

DELETE /api/v1/users/{id}/roles/{roleId}​

GET /api/v1/users/{id}/permissions​

POST /api/v1/users/bulk​

PATCH /api/v1/users/{id}/metadata​

GET /api/v1/users/me

PUT /api/v1/users/me

GET /api/v1/users/me/identities

POST /api/v1/users/me/identities/{provider}

DELETE /api/v1/users/me/identities/{provider}

GET /api/v1/auth/sessions

DELETE /api/v1/auth/sessions/{id}

DELETE /api/v1/auth/sessions

GET /api/v1/users

GET /api/v1/users/{id}

POST /api/v1/users

PUT /api/v1/users/{id}

DELETE /api/v1/users/{id}

POST /api/v1/users/{id}/suspend

POST /api/v1/users/{id}/reactivate

POST /api/v1/users/{id}/unlock

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

DELETE /api/v1/users/{id}/roles/{roleId}

GET /api/v1/users/{id}/permissions

POST /api/v1/users/bulk

PATCH /api/v1/users/{id}/metadata