المصادقة الثنائية

أضف طبقة أمان إضافية إلى حساب MailLand الخاص بك باستخدام المصادقة الثنائية المبنية على TOTP. عند تفعيلها، يتطلب تسجيل الدخول كلاً من كلمة المرور ورمز زمني من تطبيق المصادقة.

إعداد المصادقة الثنائيةنسخ رابط القسم

POST https://api.mail.land/v1/auth/2fa/setup

curl -X POST https://api.mail.land/v1/auth/2fa/setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "secret": "JBSWY3DPEHPK3PXP",
  "secretMasked": "JBSW...3PXP",
  "otpAuthUri": "otpauth://totp/MailLand:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=MailLand",
  "qrCodeDataUri": "data:image/png;base64,iVBORw0KGgo...",
  "backupCodes": [
    "A1B2C3D4",
    "E5F6G7H8",
    "I9J0K1L2",
    "M3N4O5P6",
    "Q7R8S9T0",
    "U1V2W3X4",
    "Y5Z6A7B8",
    "C9D0E1F2",
    "G3H4I5J6",
    "K7L8M9N0"
  ]
}

POST https://api.mail.land/v1/auth/2fa/enable

{
  "code": "123456"
}

curl -X POST https://api.mail.land/v1/auth/2fa/enable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

{
  "message": "Two-factor authentication enabled successfully"
}

التحقق من رمزنسخ رابط القسم

عندما يُرجع تسجيل الدخول requiresTwoFactor: true، أكمل المصادقة بالتحقق من رمز TOTP:

POST https://api.mail.land/v1/auth/2fa/verify

{
  "challengeId": "2fa_challenge_abc123",
  "code": "123456",
  "trustDevice": true
}

trustDevice اختياري. عند تعيينه إلى true، يتم تذكر الجهاز لمدة 30 يوماً وتُتخطى المصادقة الثنائية في تسجيلات الدخول اللاحقة منه.

curl -X POST https://api.mail.land/v1/auth/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "2fa_challenge_abc123",
    "code": "123456"
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_a1b2c3d4e5...",
  "deviceTrusted": false
}

لا يوجد expiresIn ولا كائن user في هذه الاستجابة. تكون قيمة deviceTrusted هي true عندما كان trustDevice مضبوطاً على true. أما رمز الجهاز نفسه فلا يظهر في جسم الاستجابة أبداً: تضعه الواجهة البرمجية في ملف تعريف الارتباط HttpOnly المسمى __Host-trusted_device، ويرسله المتصفح عند تسجيل الدخول التالي.

استخدام رمز النسخ الاحتياطينسخ رابط القسم

في حال فقدان الوصول إلى تطبيق المصادقة، استخدم رمز نسخ احتياطي بدلاً منه:

POST https://api.mail.land/v1/auth/2fa/verify-backup

{
  "challengeId": "2fa_challenge_abc123",
  "code": "a1b2c3d4"
}

الحقل هو code (8-10 أحرف)، وليس backupCode.

curl -X POST https://api.mail.land/v1/auth/2fa/verify-backup \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "2fa_challenge_abc123",
    "code": "a1b2c3d4"
  }'

يُرجع الاستجابة ذاتها كالتحقق عبر TOTP. يمكن استخدام كل رمز نسخ احتياطي مرة واحدة فقط.

إعادة توليد رموز النسخ الاحتياطينسخ رابط القسم

أنشئ مجموعة جديدة من رموز النسخ الاحتياطي (يبطل كل الرموز السابقة). يتطلب رمز TOTP حالي:

POST https://api.mail.land/v1/auth/2fa/backup-codes/regenerate

{
  "code": "123456"
}

curl -X POST https://api.mail.land/v1/auth/2fa/backup-codes/regenerate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

[
  "X2Y3Z4A5",
  "B6C7D8E9",
  "F2G3H4J5",
  "K6L7M8N9",
  "P2Q3R4S5",
  "T6U7V8W9",
  "X6Y7Z8A9",
  "B2C3D4E5",
  "F6G7H8J9",
  "K2L3M4N5"
]

الاستجابة عبارة عن مصفوفة JSON مجردة من السلاسل النصية، وليست { "backupCodes": [...] }.

التحقق من حالة المصادقة الثنائيةنسخ رابط القسم

GET https://api.mail.land/v1/auth/2fa/status

curl https://api.mail.land/v1/auth/2fa/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "isEnabled": true,
  "enabledAt": "2026-01-15T10:00:00Z",
  "backupCodesRemaining": 6,
  "trustedDevicesCount": 2
}

الأجهزة الموثوقةنسخ رابط القسم

عند التحقق من المصادقة الثنائية، يمكن تذكّر الجهاز لتخطي المصادقة الثنائية في عمليات تسجيل الدخول المستقبلية من المتصفح ذاته.

قائمة الأجهزة الموثوقةنسخ رابط القسم

GET https://api.mail.land/v1/auth/2fa/devices

curl https://api.mail.land/v1/auth/2fa/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "id": "dev_a1b2c3d4e5",
    "deviceName": "Chrome on macOS",
    "ipAddress": "203.0.113.10",
    "createdAt": "2026-01-20T14:00:00Z",
    "expiresAt": "2026-02-19T14:00:00Z",
    "lastUsedAt": "2026-02-17T09:00:00Z",
    "isCurrent": true
  },
  {
    "id": "dev_f6g7h8i9j0",
    "deviceName": "Firefox on Windows",
    "ipAddress": "198.51.100.24",
    "createdAt": "2026-02-01T08:00:00Z",
    "expiresAt": "2026-03-03T08:00:00Z",
    "lastUsedAt": "2026-02-16T15:30:00Z",
    "isCurrent": false
  }
]

الاستجابة عبارة عن مصفوفة مجردة، وليست { "devices": [...] }، والحقول هي deviceName وipAddress وexpiresAt وisCurrent بدلاً من name.

إلغاء ثقة جهازنسخ رابط القسم

DELETE https://api.mail.land/v1/auth/2fa/devices/{id}

يعيد 204 عند النجاح، أو 404 RESOURCE_NOT_FOUND إذا كان معرّف الجهاز لا يخص المستخدم الحالي.

curl -X DELETE https://api.mail.land/v1/auth/2fa/devices/dev_a1b2c3d4e5 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

إلغاء ثقة جميع الأجهزةنسخ رابط القسم

DELETE https://api.mail.land/v1/auth/2fa/devices

curl -X DELETE https://api.mail.land/v1/auth/2fa/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يُلغي ثقة جميع الأجهزة، مما يستوجب التحقق من المصادقة الثنائية عند تسجيل الدخول التالي من كل جهاز.

يؤدي تغيير كلمة المرور أو إعادة تعيينها أو تسجيل الخروج من جميع الجلسات (POST /v1/auth/revoke-all-tokens) أيضًا إلى إلغاء ثقة جميع الأجهزة بالطريقة نفسها.

تعطيل المصادقة الثنائيةنسخ رابط القسم

POST https://api.mail.land/v1/auth/2fa/disable

{
  "code": "123456"
}

curl -X POST https://api.mail.land/v1/auth/2fa/disable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

يتطلب رمز TOTP أو رمز نسخ احتياطي صالح لتأكيد العملية: يُجرَّب رمز TOTP أولاً، ولا يُقبل رمز النسخ الاحتياطي إلا إذا فشل التحقق من TOTP. يؤدي تعطيل المصادقة الثنائية إلى إبطال جميع رموز النسخ الاحتياطي والأجهزة الموثوقة.

استجابات الخطأنسخ رابط القسم

معظم حالات الفشل (رمز غير صالح أو منتهي الصلاحية، حالة خاطئة، إعادة استخدام رمز نسخ احتياطي) تُعيد 400 INVALID_REQUEST مع رسالة. أما جسم الطلب غير الصالح (طول رمز خاطئ، challengeId مفقود، إلخ) فيفشل في التحقق من صحة الحقول أولاً ويُعيد 400 VALIDATION_FAILED بدلاً من ذلك. الجهاز غير المعروف يُعيد 404 RESOURCE_NOT_FOUND. لا يوجد رمز منفصل مثل INVALID_CODE أو TWO_FACTOR_* أو CHALLENGE_EXPIRED.

الخطوات التاليةنسخ رابط القسم

• المصادقة: تسجيل الدخول وإدارة الرموز
• إدارة الفريق: إدارة وصول الفريق
• مساحات العمل: إعدادات مساحة العمل