احراز هویت دو مرحله‌ای

با استفاده از احراز هویت دو مرحله‌ای مبتنی بر TOTP، یک لایه امنیتی اضافی به حساب MailLand خود اضافه کنید. پس از فعال‌سازی، ورود به سیستم به هر دو مورد نیاز دارد: رمز عبور و یک کد زمان‌محور از برنامه احراز هویت.

راه‌اندازی 2FAکپی پیوند بخش

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 باشد، دستگاه به مدت ۳۰ روز به خاطر سپرده می‌شود و ۲FA در ورودهای بعدی از آن دستگاه نادیده گرفته می‌شود.

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 در این پاسخ وجود ندارد. وقتی trustDevice برابر true بوده باشد، deviceTrusted برابر true است. خود توکن دستگاه هرگز در بدنهٔ پاسخ نمی‌آید: API آن را در کوکی HttpOnly به نام __Host-trusted_device قرار می‌دهد و مرورگر آن را در ورود بعدی خودش می‌فرستد.

استفاده از کد پشتیبانکپی پیوند بخش

در صورت از دست دادن دسترسی به برنامه احراز هویت، از یک کد پشتیبان استفاده کنید:

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

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

نام فیلد code است (۸ تا ۱۰ کاراکتر)، نه 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": [...] }.

بررسی وضعیت 2FAکپی پیوند بخش

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
}

دستگاه‌های مورد اعتمادکپی پیوند بخش

هنگام تأیید 2FA، دستگاه می‌تواند به خاطر سپرده شود تا در ورودهای بعدی از همان مرورگر، 2FA نیاز نباشد.

فهرست دستگاه‌های مورد اعتمادکپی پیوند بخش

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..."

دسترسی تمام دستگاه‌های مورد اعتماد را لغو می‌کند و در ورود بعدی از هر دستگاه، تأیید 2FA الزامی خواهد بود.

تغییر رمز عبور، بازنشانی آن و خروج از همهٔ نشست‌ها (POST /v1/auth/revoke-all-tokens) نیز به همین شکل دسترسی تمام دستگاه‌های مورد اعتماد را لغو می‌کنند.

غیرفعال‌سازی 2FAکپی پیوند بخش

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 ناموفق باشد. غیرفعال‌کردن ۲FA همه‌ی کدهای پشتیبان و دستگاه‌های مورد اعتماد را باطل می‌کند.

پاسخ‌های خطاکپی پیوند بخش

بیشتر شکست‌ها (کد نامعتبر یا منقضی، وضعیت اشتباه، استفاده‌ی مجدد از کد پشتیبان) کد 400 INVALID_REQUEST همراه با یک پیام برمی‌گردانند. اما بدنه‌ی درخواستِ نادرست (طول کد اشتباه، نبودِ challengeId و مانند آن) ابتدا در اعتبارسنجی فیلدها شکست می‌خورد و به‌جای آن 400 VALIDATION_FAILED برمی‌گرداند. دستگاه ناشناخته کد 404 RESOURCE_NOT_FOUND برمی‌گرداند. هیچ کد جداگانه‌ای مانند INVALID_CODE، TWO_FACTOR_* یا CHALLENGE_EXPIRED وجود ندارد.

مراحل بعدیکپی پیوند بخش

• احراز هویت: ورود به سیستم و مدیریت توکن
• مدیریت تیم: مدیریت دسترسی تیم
• فضاهای کاری: تنظیمات فضای کاری