Authentication API

كل Authentication Endpoints عامة (لا تتطلب Bearer Token) ما لم يُذكر خلاف ذلك. جميعها تخضع لـ Rate Limiting. أضف Header الـ X-Tenant-ID عندما لا يمكن استنتاج المستفيد من الـ Request.

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

---

POST /api/v1/auth/resolve-tenant

تحديد المستفيد المرتبط ببريد إلكتروني قبل تسجيل الدخول. استخدم هذا الـ Endpoint عندما تحتاج واجهة تسجيل الدخول لتوجيه المستخدمين إلى المستفيد الصحيح بدون معرفة الـ Tenant ID.

Request Body

Field	Type	Required	الوصف
email	string	Yes	البريد الإلكتروني للمستخدم

curl -X POST "https://api.ithbat.io/api/v1/auth/resolve-tenant" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response 200

{
  "success": true,
  "data": {
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "tenantSlug": "acme",
    "tenantName": "Acme Corporation"
  }
}

Error Codes

Code	HTTP	الوصف
TENANT_NOT_FOUND	404	لا يوجد مستفيد مرتبط بنطاق هذا البريد الإلكتروني

---

POST /api/v1/auth/login

مصادقة مستخدم بالبريد الإلكتروني وكلمة المرور. يرجع JWT Tokens. إذا كانت MFA مفعلة، الـ Response يتضمن mfaRequired: true و mfaToken لاستخدامه في خطوة التحقق.

Request Body

Field	Type	Required	الوصف
email	string	Yes	البريد الإلكتروني للمستخدم
password	string	Yes	كلمة المرور
organizationId	string	No	تقييد تسجيل الدخول بمؤسسة محددة

curl -X POST "https://api.ithbat.io/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -d '{
    "email": "[email protected]",
    "password": "correct-horse-battery-staple"
  }'

Response 200 — نجاح

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
      "email": "[email protected]",
      "firstName": "Alice",
      "fatherName": "",
      "grandfatherName": "",
      "familyName": "Smith",
      "displayName": "Alice Smith",
      "roles": ["admin"],
      "permissions": ["admin"]
    }
  }
}

Response 200 — مطلوب MFA

{
  "success": true,
  "data": {
    "mfaRequired": true,
    "mfaToken": "mfa_eyJhbGciOiJIUzI1NiJ9...",
    "accessToken": "",
    "refreshToken": "",
    "idToken": "",
    "tokenType": "Bearer",
    "expiresIn": 0
  }
}

عندما يكون mfaRequired بقيمة true، استدعِ POST /api/v1/auth/mfa/verify مع الـ mfaToken وكود TOTP الخاص بالمستخدم.

Error Codes

Code	HTTP	الوصف
INVALID_CREDENTIALS	401	البريد الإلكتروني أو كلمة المرور غير صحيحة
ACCOUNT_SUSPENDED	403	الحساب موقوف
ACCOUNT_NOT_VERIFIED	403	لم يتم التحقق من البريد الإلكتروني
TENANT_NOT_FOUND	404	المستفيد غير موجود
TENANT_SUSPENDED	403	حساب المستفيد موقوف

---

POST /api/v1/auth/register

تسجيل حساب مستخدم جديد في المستفيد الحالي. يتم إرسال بريد تحقق عند نجاح التسجيل.

Request Body

Field	Type	Required	الوصف
email	string	Yes	البريد الإلكتروني
firstName	string	Yes	الاسم الأول
fatherName	string	No	اسم الأب (نظام التسمية العربي)
grandfatherName	string	No	اسم الجد (نظام التسمية العربي)
familyName	string	Yes	اسم العائلة
password	string	Yes	كلمة المرور (يجب أن تستوفي سياسة المستفيد)

curl -X POST "https://api.ithbat.io/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -d '{
    "email": "[email protected]",
    "firstName": "Bob",
    "familyName": "Jones",
    "password": "SecurePass@2024"
  }'

Response 201

{
  "success": true,
  "data": {
    "userId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "email": "[email protected]",
    "displayName": "Bob Jones",
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "message": "Registration successful. Please verify your email address."
  }
}

Error Codes

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

---

POST /api/v1/auth/refresh

استبدال Refresh Token صالح بزوج جديد من Access Token و Refresh Token. الـ Refresh Token القديم يتم إبطاله.

Request Body

Field	Type	Required	الوصف
refreshToken	string	Yes	Refresh Token صالح

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

Response 200

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600
  }
}

Error Codes

Code	HTTP	الوصف
TOKEN_INVALID	401	الـ Refresh Token غير صالح أو تم إبطاله
TOKEN_EXPIRED	401	انتهت صلاحية الـ Refresh Token

---

POST /api/v1/auth/logout

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

إبطال الـ Session الحالي. يمكن اختياريا إبطال الـ Refresh Token لمنع استخدامه مجددا.

Request Body

Field	Type	Required	الوصف
refreshToken	string	No	الـ Refresh Token المراد إبطاله مع الـ Session

curl -X POST "https://api.ithbat.io/api/v1/auth/logout" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}'

Response 200

{
  "success": true,
  "message": "Logged out successfully"
}

---

POST /api/v1/auth/change-password

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

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

Request Body

Field	Type	Required	الوصف
current_password	string	Yes	كلمة المرور الحالية
new_password	string	Yes	كلمة المرور الجديدة (8 أحرف كحد أدنى)
revoke_other_sessions	boolean	No	إبطال كل الـ Sessions عدا الحالي (الافتراضي: false)

curl -X POST "https://api.ithbat.io/api/v1/auth/change-password" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPass@2023",
    "new_password": "NewPass@2024",
    "revoke_other_sessions": true
  }'

Response 200

{
  "success": true,
  "data": {
    "message": "Password changed successfully"
  }
}

Error Codes

Code	HTTP	الوصف
INVALID_CREDENTIALS	401	كلمة المرور الحالية غير صحيحة
VALIDATION_ERROR	400	كلمة المرور الجديدة لا تستوفي متطلبات السياسة

---

POST /api/v1/auth/password-reset/initiate

طلب إرسال بريد إعادة تعيين كلمة المرور. يرجع دائما 200 لمنع كشف عناوين البريد الإلكتروني، بغض النظر عن وجود الحساب.

Request Body

Field	Type	Required	الوصف
email	string	Yes	البريد الإلكتروني المرتبط بالحساب

curl -X POST "https://api.ithbat.io/api/v1/auth/password-reset/initiate" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -d '{"email": "[email protected]"}'

Response 200

{
  "success": true,
  "data": {
    "message": "If an account exists for this email, a password reset link has been sent."
  }
}

---

POST /api/v1/auth/password-reset/validate

التحقق من صلاحية Token إعادة تعيين كلمة المرور قبل عرض فورم إعادة التعيين. هذا يتجنب عرض الفورم ليفشل بعد الإرسال.

Request Body

Field	Type	Required	الوصف
token	string	Yes	الـ Token من رابط بريد إعادة التعيين

curl -X POST "https://api.ithbat.io/api/v1/auth/password-reset/validate" \
  -H "Content-Type: application/json" \
  -d '{"token": "prst_abc123xyz..."}'

Response 200

{
  "success": true,
  "data": {
    "valid": true
  }
}

Response 200 — Token غير صالح

{
  "success": true,
  "data": {
    "valid": false,
    "message": "Token is invalid or has expired"
  }
}

---

POST /api/v1/auth/password-reset/complete

إتمام إعادة تعيين كلمة المرور باستخدام الـ Token من بريد إعادة التعيين.

Request Body

Field	Type	Required	الوصف
token	string	Yes	الـ Token من رابط بريد إعادة التعيين
newPassword	string	Yes	كلمة المرور الجديدة (يجب أن تستوفي سياسة المستفيد)

curl -X POST "https://api.ithbat.io/api/v1/auth/password-reset/complete" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "prst_abc123xyz...",
    "newPassword": "NewSecurePass@2024"
  }'

Response 200

{
  "success": true,
  "data": {
    "message": "Password has been reset successfully. You can now log in with your new password."
  }
}

Error Codes

Code	HTTP	الوصف
TOKEN_INVALID	400	الـ Reset Token غير صالح أو سبق استخدامه
TOKEN_EXPIRED	400	انتهت صلاحية الـ Reset Token
VALIDATION_ERROR	400	كلمة المرور الجديدة لا تستوفي متطلبات السياسة

---

POST /api/v1/auth/verify-email

التحقق من البريد الإلكتروني للمستخدم باستخدام الـ Token من بريد التحقق.

Request Body

Field	Type	Required	الوصف
token	string	Yes	الـ Token من بريد التحقق

curl -X POST "https://api.ithbat.io/api/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{"token": "vfy_abc123xyz..."}'

Response 200

{
  "success": true,
  "data": {
    "message": "Email address verified successfully"
  }
}

Error Codes

Code	HTTP	الوصف
TOKEN_INVALID	400	Token التحقق غير صالح أو سبق استخدامه
TOKEN_EXPIRED	400	انتهت صلاحية Token التحقق

---

POST /api/v1/auth/resend-verification

إعادة إرسال بريد التحقق إلى العنوان المحدد.

Request Body

Field	Type	Required	الوصف
email	string	Yes	البريد الإلكتروني الذي يحتاج تحقق

curl -X POST "https://api.ithbat.io/api/v1/auth/resend-verification" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -d '{"email": "[email protected]"}'

Response 200

{
  "success": true,
  "message": "Verification email sent"
}

---

POST /api/v1/auth/passwordless/start

إرسال Magic Link إلى البريد الإلكتروني المحدد. الرابط صالح لمدة 15 دقيقة.

Request Body

Field	Type	Required	الوصف
email	string	Yes	البريد الإلكتروني لإرسال الـ Magic Link إليه
tenant_id	string	No	Tenant ID (مطلوب إذا لم يكن في Header الـ X-Tenant-ID)

curl -X POST "https://api.ithbat.io/api/v1/auth/passwordless/start" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -d '{"email": "[email protected]"}'

Response 200

{
  "success": true,
  "data": {
    "message": "Magic link sent. Check your email to continue."
  }
}

---

POST /api/v1/auth/passwordless/verify

التحقق من Token الـ Magic Link واستبداله بـ JWT Tokens.

Request Body

Field	Type	Required	الوصف
token	string	Yes	الـ Token من URL الـ Magic Link
tenant_id	string	No	Tenant ID (مطلوب إذا لم يكن في Header الـ X-Tenant-ID)

curl -X POST "https://api.ithbat.io/api/v1/auth/passwordless/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "plnk_abc123xyz...",
    "tenant_id": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"
  }'

Response 200

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "[email protected]",
      "displayName": "Alice Smith",
      "roles": ["user"],
      "permissions": ["user:read"]
    }
  }
}

Error Codes

Code	HTTP	الوصف
TOKEN_INVALID	400	Token الـ Magic Link غير صالح أو سبق استخدامه
TOKEN_EXPIRED	400	انتهت صلاحية الـ Magic Link (صالح لمدة 15 دقيقة)

---

GET /api/v1/auth/social/{provider}/login

بدء Social Login Flow. يعمل Redirect للمتصفح إلى صفحة التفويض الخاصة بالـ Identity Provider. الـ Providers المدعومة: google، github، microsoft، apple.

Path Parameters

Parameter	Type	الوصف
provider	string	اسم الـ Identity Provider (مثال: google، github)

Query Parameters

Parameter	Type	Required	الوصف
redirect_uri	string	No	الـ Redirect URI بعد المصادقة
state	string	No	قيمة opaque للحماية من CSRF

curl -L "https://api.ithbat.io/api/v1/auth/social/google/login?redirect_uri=https%3A%2F%2Fapp.acme.com%2Fcallback" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

هذا الـ Endpoint يرجع HTTP 302 ويعمل Redirect إلى OAuth Authorization URL الخاص بـ Google.

---

GET /api/v1/auth/social/{provider}/callback

OAuth Callback Endpoint. الـ Identity Provider يعمل Redirect إلى هنا بعد تفويض المستخدم. Ithbat يستبدل الـ Authorization Code، وينشئ حساب المستخدم أو يربطه، ثم يعمل Redirect إلى تطبيقك مع JWT Tokens.

هذا الـ Endpoint يُستدعى من قِبل الـ Identity Provider — تطبيقك لا يستدعيه مباشرة. اضبط Redirect URI الخاص بـ OAuth App على https://api.ithbat.io/api/v1/auth/social/{provider}/callback.

---

POST /api/v1/auth/mfa/setup

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

تهيئة إعداد TOTP MFA للمستخدم المصادق عليه. يرجع TOTP Secret و QR Code URI لعرضه على المستخدم.

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

Response 200

{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCodeUri": "otpauth://totp/Ithbat%3Aalice%40acme.com?secret=JBSWY3DPEHPK3PXP&issuer=Ithbat",
    "backupCodes": [
      "12345-67890",
      "23456-78901",
      "34567-89012",
      "45678-90123",
      "56789-01234",
      "67890-12345",
      "78901-23456",
      "89012-34567"
    ]
  }
}

بعد استدعاء Setup، استدعي POST /api/v1/auth/mfa/verify-setup مع كود TOTP صالح لتفعيل MFA.

---

POST /api/v1/auth/mfa/verify-setup

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

تأكيد إعداد MFA بتقديم أول كود TOTP صالح من تطبيق المصادقة. MFA لا تتفعل حتى إتمام هذه الخطوة.

Request Body

Field	Type	Required	الوصف
code	string	Yes	كود TOTP المكوّن من 6 أرقام من تطبيق المصادقة

curl -X POST "https://api.ithbat.io/api/v1/auth/mfa/verify-setup" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Response 200

{
  "success": true,
  "message": "MFA enabled successfully"
}

---

POST /api/v1/auth/mfa/verify

التحقق من كود MFA أثناء تسجيل الدخول. استخدم الـ mfaToken من Login Response.

Request Body

Field	Type	Required	الوصف
mfaToken	string	Yes	الـ MFA Token من Login Response
code	string	Yes	كود TOTP المكوّن من 6 أرقام من تطبيق المصادقة

curl -X POST "https://api.ithbat.io/api/v1/auth/mfa/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "mfaToken": "mfa_eyJhbGciOiJIUzI1NiJ9...",
    "code": "123456"
  }'

Response 200

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "[email protected]",
      "displayName": "Alice Smith",
      "roles": ["admin"],
      "permissions": ["admin"]
    }
  }
}

Error Codes

Code	HTTP	الوصف
MFA_TOKEN_INVALID	401	الـ MFA Token غير صالح أو منتهي الصلاحية
MFA_CODE_INVALID	401	كود TOTP غير صحيح
MFA_CODE_ALREADY_USED	401	كود TOTP هذا سبق استخدامه

---

POST /api/v1/auth/mfa/verify-backup

التحقق من Backup Code أثناء تسجيل الدخول عندما تطبيق المصادقة غير متوفر. كل Backup Code يُستخدم مرة واحدة فقط.

Request Body

Field	Type	Required	الوصف
mfaToken	string	Yes	الـ MFA Token من Login Response
backupCode	string	Yes	أحد الـ Backup Codes من إعداد MFA

curl -X POST "https://api.ithbat.io/api/v1/auth/mfa/verify-backup" \
  -H "Content-Type: application/json" \
  -d '{
    "mfaToken": "mfa_eyJhbGciOiJIUzI1NiJ9...",
    "backupCode": "12345-67890"
  }'

Response 200 — نفس Token Response الخاص بـ POST /api/v1/auth/mfa/verify.

---

SAML 2.0 Endpoints

لـ Enterprise SSO القائم على SAML، Ithbat يوفر Service Provider Endpoints لكل مستفيد.

Method	Path	الوصف
GET	/api/v1/auth/saml/{tenant_id}/metadata	تحميل SP Metadata بصيغة XML لإعداد الـ IdP
GET	/api/v1/auth/saml/{tenant_id}/login	بدء SAML Login (يعمل Redirect إلى الـ IdP)
POST	/api/v1/auth/saml/{tenant_id}/acs	Assertion Consumer Service — يستقبل SAML Response من الـ IdP

اضبط SAML Identity Provider باستخدام الـ Metadata URL:

https://api.ithbat.io/api/v1/auth/saml/{tenant_id}/metadata

راجع دليل إعداد SAML للتعليمات الكاملة.

---

Social Provider List

GET /api/v1/auth/social/providers

عرض الـ Social Login Providers المفعّلة للمستفيد الحالي.

curl "https://api.ithbat.io/api/v1/auth/social/providers" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "providers": [
      { "id": "google", "name": "Google", "enabled": true },
      { "id": "microsoft", "name": "Microsoft", "enabled": true },
      { "id": "github", "name": "GitHub", "enabled": false }
    ]
  }
}