البداية السريعة

هذا الدليل يأخذك من الصفر إلى أول Authenticated API Call. بنهايته تكون قد سجّلت مستخدمًا وسجّلت دخوله وأجريت Request مصادقًا عليه باستخدام الـ JWT.

المتطلبات

• حساب في Ithbat IAM — سجّل في ithbat.io
• curl أو أي HTTP Client (مثل Postman أو Insomnia)
• Node.js 18+ إذا كنت ترغب في استخدام TypeScript SDK

---

الخطوة 1: إنشاء حسابك والـ Tenant

انتقل إلى ithbat.io وسجّل. أثناء عملية التهيئة تنشئ أول Tenant — وهو نطاق هوية رقمية معزول لتطبيقك. أعطه اسمًا (مثلاً "تطبيقي - بيئة التطوير") واختر منطقة البيانات المفضلة (عالمي، المملكة العربية السعودية، أو مصر).

بعد الإنشاء، لوحة التحكم تعرض Tenant ID — وهو UUID يبدو مثل 3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c. احتفظ به؛ ستمرره في كل API Request عبر Header الـ X-Tenant-ID.

---

الخطوة 2: الحصول على Credentials

لتدفقات مصادقة المستخدم النهائي (التسجيل، تسجيل الدخول)، تحتاج فقط Tenant ID — هذه الـ Endpoints عامة لكنها مرتبطة بالـ Tenant.

للعمليات الإدارية (إدارة المستخدمين، إدارة الأدوار، إلخ) تحتاج Access Token صالح عبر تسجيل الدخول كمستخدم بصلاحيات المسؤول.

نصيحة

خزّن الـ Tenant ID والـ Credentials في Environment Variables ولا ترفعها أبدًا لـ Version Control.

---

الخطوة 3: تثبيت SDK (اختياري)

إذا كنت تفضّل استخدام Typed Client بدلًا من Raw HTTP Requests، ثبّت TypeScript SDK:

npm install @ithbatiam/sdk

يمكنك المتابعة باستخدام أمثلة cURL أو SDK خلال هذا الدليل.

---

الخطوة 4: تسجيل أول مستخدم

Registration Endpoint ينشئ مستخدمًا جديدًا في الـ Tenant. الـ Header X-Tenant-ID مطلوب.

حقول الـ Request:

• email — مطلوب
• firstName — اختياري
• familyName — اختياري
• password — اختياري (إذا لم يُرسَل، يُعامَل كدعوة)

curl -X POST https://api.ithbat.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "familyName": "Doe",
    "password": "SecurePass123!"
  }'

Response (201 Created):

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "displayName": "Jane Doe",
  "tenantId": "3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "message": "Registration successful. Please verify your email."
}

SDK:

import { IthbatSDK } from '@ithbatiam/sdk';

const ithbat = new IthbatSDK({
  basePath: 'https://api.ithbat.io/api/v1',
  tenantId: process.env.ITHBAT_TENANT_ID,
});

const result = await ithbat.auth.register({
  email: '[email protected]',
  firstName: 'Jane',
  familyName: 'Doe',
  password: 'SecurePass123!',
  tenantId: process.env.ITHBAT_TENANT_ID,
});

ملاحظة

Ithbat IAM يرسل بريد تحقق بعد التسجيل. في بيئة التطوير يمكنك تهيئة إعدادات التحقق من البريد في لوحة التحكم، أو إنشاء مستخدمين عبر Admin API.

---

الخطوة 5: مصادقة المستخدم

بعد التسجيل، سجّل دخول المستخدم للحصول على JWT Tokens.

curl -X POST https://api.ithbat.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenantId": "3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "email": "[email protected]",
    "firstName": "Jane",
    "familyName": "Doe",
    "displayName": "Jane Doe",
    "roles": [],
    "permissions": []
  }
}

إذا كانت mfaRequired تساوي true، فالـ accessToken والـ refreshToken غائبان. مرّر الـ mfaToken إلى POST /api/v1/auth/mfa/verify مع رمز TOTP لإكمال تسجيل الدخول.

SDK:

const result = await ithbat.auth.login({
  email: '[email protected]',
  password: 'SecurePass123!',
});

if (result.mfaRequired) {
  const mfaResult = await ithbat.auth.verifyMfa({
    mfaToken: result.mfaToken,
    code: '123456',
  });
  ithbat.setAccessToken(mfaResult.accessToken);
} else {
  ithbat.setAccessToken(result.accessToken);
}

---

الخطوة 6: إجراء Authenticated Request

استخدم الـ accessToken من Response تسجيل الدخول لاستدعاء الـ Protected Endpoints. مرّره كـ Bearer Token في Header الـ Authorization.

curl https://api.ithbat.io/api/v1/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Response (200 OK):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenantId": "3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "email": "[email protected]",
  "firstName": "Jane",
  "fatherName": "",
  "grandfatherName": "",
  "familyName": "Doe",
  "displayName": "Jane Doe",
  "status": "active",
  "roles": [],
  "mfaEnabled": false,
  "createdAt": "2026-02-24T10:00:00Z",
  "updatedAt": "2026-02-24T10:00:00Z"
}

SDK:

const me = await ithbat.auth.me();
console.log(me.email);

---

الخطوة 7: عرض المستخدمين (إداري)

عرض المستخدمين في المستفيد. يتطلب صلاحية user:read.

curl "https://api.ithbat.io/api/v1/users?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

SDK:

const result = await ithbat.users.listUsers({ page: 1, limit: 25 });
console.log(result.items);       // User[]
console.log(result.totalItems);  // total count

listUsers() ترجع PagedResult<User> مع .items و .totalItems.

---

الخطوة 8: تحديث الـ Access Token

الـ Access Tokens تنتهي صلاحيتها بعد expiresIn ثانية (الافتراضي 3600). استخدم الـ Refresh Token للحصول على Access Token جديد.

curl -X POST https://api.ithbat.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "rt_aBcDeFgHiJkLmNoPqRsTuVwXyZ..."
  }'

Response (200 OK):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_newRefreshTokenHere...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

تحذير

Ithbat IAM يستخدم Refresh Token Rotation. كل استدعاء لـ Refresh Endpoint يصدر Refresh Token جديدًا ويُبطل السابق. احتفظ دائمًا بأحدث Refresh Token وتخلّص من القديم فورًا.

SDK:

const tokens = await ithbat.auth.refreshToken({ refreshToken: 'rt_...' });
ithbat.setAccessToken(tokens.accessToken);

معلومة

SDK لا يحدّث الـ Tokens تلقائيًا. استدعِ ithbat.auth.refreshToken() صراحةً عند الحاجة.

---

الخطوة 9: تسجيل الخروج

إبطال الـ Session الحالية:

curl -X POST https://api.ithbat.io/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

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

أتممت تدفق المصادقة الأساسي. إليك ما يمكنك استكشافه:

الموضوع	الرابط
فهم الـ Tenants والـ Tokens والـ RBAC	المفاهيم الأساسية
مرجع REST API الكامل	مرجع API
Authentication Endpoints	Authentication API
إدارة المستخدمين	Users API
Admin Endpoints	Admin API