احراز هویت

MailLand از دو روش احراز هویت پشتیبانی می‌کند: توکن‌های Bearer (JWT) برای نشست‌های کاربری و کلیدهای API برای یکپارچه‌سازی سرور به سرور. تمام درخواست‌های API نیازمند احراز هویت از طریق هدر Authorization هستند.

روش‌های احراز هویتکپی پیوند بخش

ثبت‌نامکپی پیوند بخش

POST https://api.mail.land/v1/auth/register

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd!",
  "fullName": "John Doe",
  "companyName": "My Company"
}

curl -X POST https://api.mail.land/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!",
    "fullName": "John Doe",
    "companyName": "My Company"
  }'

فیلدهای ناشناخته (مثلاً tenantName که به اشتباه ارسال شود) بی‌سروصدا نادیده گرفته می‌شوند.

{
  "requiresEmailVerification": true,
  "verificationTicket": "vt_abc123...",
  "maskedEmail": "u***@example.com"
}

کد وضعیت پاسخ ۲۰۱ است.

پس از ثبت‌نام، پیش از ورود به سیستم باید آدرس ایمیل را تأیید کنید.

تأیید ایمیلکپی پیوند بخش

ثبت‌نام یک کد ۶ رقمی را ایمیل می‌کند. با بدنه‌ی { "ticket": "<verificationTicket>", "code": "123456" } سراغ POST /v1/auth/verify-email-ticket بروید؛ در صورت موفقیت، پاسخ توکن‌های ورود بازگردانده می‌شود.

POST https://api.mail.land/v1/auth/verify-email-ticket

{
  "ticket": "vt_abc123...",
  "code": "123456"
}

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

ارسال مجدد ایمیل تأیید: با بدنه‌ی { "ticket": "..." } سراغ POST /v1/auth/resend-verification-ticket بروید. این درخواست نرخ‌محدود است و یک ticket تازه برمی‌گرداند.

POST https://api.mail.land/v1/auth/resend-verification-ticket

{
  "ticket": "vt_abc123..."
}

curl -X POST https://api.mail.land/v1/auth/resend-verification-ticket \
  -H "Content-Type: application/json" \
  -d '{"ticket": "vt_abc123..."}'

ورود به سیستمکپی پیوند بخش

POST https://api.mail.land/v1/auth/login

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!"
  }'

پاسخکپی پیوند بخش

پاسخ ورود بر اساس وضعیت حساب کاربری متفاوت است:

ورود موفق:

{
  "userId": "v4j2x7n1m9k5p3",
  "email": "[email protected]",
  "fullName": "John Doe",
  "avatarUrl": null,
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_a1b2c3d4e5...",
  "expiresAt": "2026-09-25T13:00:00Z",
  "requiresTwoFactor": false,
  "twoFactorChallengeId": null,
  "tenantCount": 1,
  "activeTenantId": "k3m9x2p7qw4rtz",
  "activeTenantName": "My Company",
  "requiresEmailVerification": false,
  "verificationTicket": null,
  "maskedEmail": null
}

هیچ آبجکت user و هیچ فیلد role در پاسخ وجود ندارد. حساب تأییدنشده کد ۲۰۰ همراه با requiresEmailVerification: true و یک verificationTicket دریافت می‌کند، نه یک خطا.

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

{
  "accessToken": null,
  "refreshToken": null,
  "requiresTwoFactor": true,
  "twoFactorChallengeId": "2fa_challenge_abc123"
}

هنگامی که requiresTwoFactor برابر true است، پیش از دریافت توکن‌ها، تأیید ۲FA را تکمیل کنید.

تجدید توکنکپی پیوند بخش

توکن‌های دسترسی پس از ۶۰ دقیقه منقضی می‌شوند. برای دریافت توکن دسترسی جدید از توکن تجدید استفاده کنید:

POST https://api.mail.land/v1/auth/refresh-token

{
  "refreshToken": "rt_a1b2c3d4e5..."
}

curl -X POST https://api.mail.land/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "rt_a1b2c3d4e5..."}'

این پاسخ همان شکل پاسخ ورود بالا (شیء کامل AuthResponse) را دارد، نه فقط این سه فیلد:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-09-25T14:00:00Z"
}

خروج از سیستمکپی پیوند بخش

ابطال نشست جاری:

POST https://api.mail.land/v1/auth/logout

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

ابطال تمام نشست‌های فعال:

POST https://api.mail.land/v1/auth/revoke-all-tokens

curl -X POST https://api.mail.land/v1/auth/revoke-all-tokens \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

مدیریت رمز عبورکپی پیوند بخش

فراموشی رمز عبورکپی پیوند بخش

POST https://api.mail.land/v1/auth/forgot-password

{
  "email": "[email protected]"
}

curl -X POST https://api.mail.land/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

یک ایمیل بازنشانی رمز عبور با یک توکن محدود به زمان ارسال می‌کند.

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

POST https://api.mail.land/v1/auth/reset-password

confirmPassword الزامی است و باید با newPassword یکسان باشد؛ همان قوانین پیچیدگی رمز عبور هنگام ثبت‌نام اینجا هم اعمال می‌شود.

{
  "token": "reset-token-from-email",
  "newPassword": "NewSecureP@ssw0rd!",
  "confirmPassword": "NewSecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "newPassword": "NewSecureP@ssw0rd!",
    "confirmPassword": "NewSecureP@ssw0rd!"
  }'

اعتبارسنجی توکن بازنشانیکپی پیوند بخش

بررسی معتبر بودن توکن بازنشانی پیش از نمایش فرم بازنشانی:

GET https://api.mail.land/v1/auth/validate-reset-token?token=reset-token-from-email

curl "https://api.mail.land/v1/auth/validate-reset-token?token=reset-token-from-email"

{
  "valid": true,
  "message": "Token is valid"
}

تغییر رمز عبورکپی پیوند بخش

تغییر رمز عبور کاربر احراز هویت شده جاری:

POST https://api.mail.land/v1/auth/change-password

{
  "currentPassword": "OldP@ssw0rd!",
  "newPassword": "NewSecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "OldP@ssw0rd!",
    "newPassword": "NewSecureP@ssw0rd!"
  }'

مدیریت پروفایلکپی پیوند بخش

دریافت کاربر جاریکپی پیوند بخش

GET https://api.mail.land/v1/auth/me

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

{
  "id": "v4j2x7n1m9k5p3",
  "email": "[email protected]",
  "fullName": "John Doe",
  "companyName": "Acme",
  "avatarUrl": "https://cdn.mail.land/avatars/usr_a1b2c3d4e5.jpg",
  "status": "Active",
  "createdAt": "2026-01-15T08:00:00Z",
  "subscription": {
    "planName": "Pro",
    "monthlyEmailLimit": 50000,
    "rateLimitPerSecond": 10,
    "startDate": "2026-01-15T08:00:00Z",
    "endDate": "2026-10-15T08:00:00Z",
    "status": "Active"
  },
  "stats": {
    "credentialCount": 3,
    "domainCount": 2
  }
}

هیچ فیلد firstName، lastName، phone، tenantId، role یا twoFactorEnabled در این پاسخ وجود ندارد.

به‌روزرسانی پروفایلکپی پیوند بخش

PUT https://api.mail.land/v1/auth/profile

فیلد fullName الزامی است؛ نبودِ companyName باعث پاک‌شدن آن می‌شود. این به‌روزرسانی صرفاً بر اساس شناسهٔ کاربر با ردیف او مطابقت پیدا می‌کند، بنابراین از هر فضای کاری‌ای که کاربر در آن فعال باشد کار می‌کند، نه فقط فضایی که حساب در آن ساخته شده است.

{
  "fullName": "Jane Smith",
  "companyName": "Acme"
}

curl -X PUT https://api.mail.land/v1/auth/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jane Smith",
    "companyName": "Acme"
  }'

آپلود تصویر پروفایلکپی پیوند بخش

POST https://api.mail.land/v1/account/avatar

یک درخواست multipart/form-data با فایل تصویر پروفایل ارسال کنید. فرمت‌های پشتیبانی‌شده: JPEG، PNG، GIF یا WebP (محتوای فایل بررسی می‌شود، نه فقط پسوند آن). حداکثر اندازه: ۱ مگابایت.

curl -X POST https://api.mail.land/v1/account/avatar \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@/path/to/avatar.jpg"

احراز هویت اجتماعیکپی پیوند بخش

MailLand از ورود اجتماعی از طریق Google، GitHub و Microsoft پشتیبانی می‌کند:

GET https://api.mail.land/auth/social/{provider}

curl https://api.mail.land/auth/social/google

GET https://api.mail.land/auth/social/{provider}/callback?code=...

curl "https://api.mail.land/auth/social/google/callback?code=authorization-code-from-provider"

POST https://api.mail.land/v1/auth/social/exchange

{
  "code": "one-time-code-from-callback-redirect"
}

curl -X POST https://api.mail.land/v1/auth/social/exchange \
  -H "Content-Type: application/json" \
  -d '{"code": "one-time-code-from-callback-redirect"}'

حذف حساب کاربریکپی پیوند بخش

حذف در سطح فضای کاری انجام می‌شود، نه در سطح حساب کاربر، و فقط یک Owner فضای کاری می‌تواند آن را آغاز کند. این عملیات به‌جای حذف فوری، حذف را پس از یک دوره‌ی مهلت زمان‌بندی می‌کند:

POST https://api.mail.land/v1/account/lifecycle/schedule-deletion

{
  "gracePeriodDays": 30
}

curl -X POST https://api.mail.land/v1/account/lifecycle/schedule-deletion \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"gracePeriodDays": 30}'

مقدار gracePeriodDays بین ۷ تا ۹۰ پذیرفته می‌شود (پیش‌فرض ۳۰)؛ مقادیر خارج از این بازه رد نمی‌شوند، بلکه به نزدیک‌ترین حد محدود می‌شوند. حذف زمان‌بندی‌شده را می‌توان هر زمان پیش از پایان دوره‌ی مهلت لغو کرد:

POST https://api.mail.land/v1/account/lifecycle/cancel-deletion

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

ایمیل تأییدنشده خطایی برنمی‌گرداند: ورود با کد ۲۰۰ همراه با requiresEmailVerification: true و یک verificationTicket تازه پاسخ می‌دهد.

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

• احراز هویت دو مرحله‌ای: افزودن ۲FA به حساب کاربری
• مدیریت تیم: دعوت از اعضای تیم
• فضاهای کاری: مدیریت چند فضای کاری
• کلیدهای API: ایجاد کلیدهای API برای دسترسی سرور به سرور