امنیت

احراز هویت

هر درخواست API را با احراز هویت استاندارد صنعتی ایمن کنید. OrbNET از رمزینه‌های حامل JWT، ورود اجتماعی OAuth2، کلیدگذر، پیوند جادویی، احراز هویت دوعاملی و کلیدهای API پشتیبانی می‌کند و برای هر یکپارچگی امنیتی انعطاف‌پذیر و در تراز تولید می‌دهد.

شروع کار

روش احراز هویت

عمر رمزینه

پشتیبانی دوعاملی

استاندارد کلیدگذر

نمای کلی روش‌های احراز هویت

OrbNET چند راهبرد احراز هویت فراهم می‌کند. همانی را برگزینید که با معماری برنامه و الزامات امنیتی شما جور است.

رمزینه‌های حامل JWT

روش اصلی احراز هویت. ایمیل و گذرواژه را با جفتی از رمزینهٔ دسترسی و رمزینهٔ تازه‌سازی مبادله کنید. رمزینه‌های دسترسی پس از ۲۴ ساعت منقضی می‌شوند و با رمزینهٔ تازه‌سازی بی‌صدا تمدید می‌شوند.

ورود اجتماعی OAuth2

بگذارید کاربران با حساب موجود گوگل یا اپل خود احراز هویت شوند. مبادلهٔ رمزینه همان جفت JWT را برمی‌گرداند و تجربهٔ ورودی روان بدون مدیریت گذرواژه می‌دهد.

کلیدگذر / WebAuthn

احراز هویت بدون گذرواژه با کلیدهای سخت‌افزاری FIDO2 یا زیست‌سنجی سکو. امن‌ترین گزینه، مقاوم در برابر فیشینگ و حملهٔ انباشت گواهی.

پیوندهای جادویی

پیوند ورود یک‌بارمصرفی به ایمیل کاربر بفرستید. نیازی به گذرواژه نیست. برای آغاز کار کم‌اصطکاک و الگوهای دسترسی کم‌تکرار ایده‌آل است.

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

با کدهای TOTP از اپ‌هایی مانند Google Authenticator یا Authy لایهٔ امنیتی دومی بیفزایید. با هر روش اصلی احراز هویت ترکیب‌شدنی است.

احراز هویت با کلید API

کلیدهای ایستای API برای یکپارچگی سرور به سرور با OrbGuard Labs. از داشبورد ساخته می‌شوند و از راه سرآیند X-API-Key داده می‌شوند.

جریان احراز هویت

برای احراز هویت و فرستادن نخستین درخواست محافظت‌شدهٔ API این گام‌ها را دنبال کنید.

گواهی‌ها را بگیرید

حساب تازه‌ای بسازید یا از گواهی‌های موجود استفاده کنید. می‌توانید با ایمیل و گذرواژه ثبت‌نام کنید، یا برای مسیری سریع‌تر از ورود اجتماعی OAuth2 استفاده کنید.

احراز هویت کنید

نقطهٔ پایانی ورود را با گواهی‌های خود فراخوانی کنید. سرور رمزینهٔ دسترسی JWT و رمزینهٔ تازه‌سازی برمی‌گرداند. اگر احراز هویت دوعاملی برای حساب روشن باشد، به‌جای آن چالش requires_2fa برمی‌گردد که با کد کاربر کامل می‌شود.

رمزینه را در درخواست‌ها بگنجانید

در هر درخواست محافظت‌شدهٔ API رمزینهٔ دسترسی را به‌عنوان رمزینهٔ حامل در سرآیند Authorization بدهید.

پس از انقضا تازه کنید

وقتی رمزینهٔ دسترسی پس از ۲۴ ساعت منقضی شد، با رمزینهٔ تازه‌سازی جفت رمزینهٔ تازه‌ای بدون احراز هویت دوباره بگیرید.

احراز هویت با رمزینهٔ حامل JWT

روش اصلی احراز هویت برای همهٔ درخواست‌های API اوربنت. گواهی‌های کاربر را با رمزینهٔ دسترسی JWT و رمزینهٔ تازه‌سازی مبادله کنید.

ورود

POST/api/v1/auth/login

با ایمیل و گذرواژه احراز هویت کنید تا رمزینه‌های دسترسی و تازه‌سازی JWT بگیرید.

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

پارامتر	نوع	الزامی	توضیحات
`email`	string	الزامی	نشانی ایمیل ثبت‌شدهٔ کاربر.
`password`	string	الزامی	گذرواژهٔ کاربر. کمینه ۸ نویسه.
`totp_code`	string	اختیاری	فقط برای حساب‌هایی با احراز هویت دوعاملی: کد ۶ رقمی اپ احرازکننده یا یک کد بازیابی. بدون آن، چنین حسابی چالش requires_2fa را دریافت می‌کند.

curl -X POST https://api.orbai.world/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

200احراز هویت موفق

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2...",
    "expiresAt": "2026-02-08T12:00:00Z",
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "role": "user"
    }
  }
}

401گواهی‌های نامعتبر

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "The email or password you entered is incorrect."
  }
}

429تلاش‌های بیش‌ازحد برای ورود

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many login attempts. Please try again later.",
    "details": {
      "retryAfter": 300
    }
  }
}

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

برای حسابی با 2FA، گذرواژهٔ درست بدون totp_code پاسخ HTTP 200 با "requires_2fa": true و یک pending_token برمی‌گرداند و هیچ رمزینه‌ای صادر نمی‌شود. ورود را در POST /api/v1/auth/2fa/complete کامل کنید یا گذرواژه را همراه totp_code دوباره بفرستید. بخش «ورود هنگامی که 2FA روشن است» را ببینید.

استفاده از رمزینهٔ دسترسی

پس از احراز هویت، رمزینهٔ دسترسی JWT را در سرآیند Authorization هر درخواست محافظت‌شده بگنجانید.

curl https://api.orbai.world/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

امنیت رمزینه

هرگز رمزینه‌های دسترسی خود را در کد سمت کلاینت، نشانی‌ها یا کنترل نسخه فاش نکنید. رمزینه‌ها را در کوکی‌های HTTP-only، ذخیره‌سازی امن محلی یا کیف کلید سکوی خود نگه دارید. رمزینه‌هایی که در نشانی یا پارامتر پرس‌وجو داده شوند رد می‌شوند.

تازه‌سازی رمزینه‌ها

رمزینه‌های دسترسی پس از ۲۴ ساعت منقضی می‌شوند. با رمزینهٔ تازه‌سازی رمزینهٔ دسترسی تازه‌ای بگیرید بی‌آنکه کاربر ناچار شود دوباره گواهی‌هایش را وارد کند.

POST/api/v1/auth/refresh

رمزینهٔ تازه‌سازی معتبر را با جفت تازه‌ای از رمزینهٔ دسترسی و تازه‌سازی مبادله کنید.

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

پارامتر	نوع	الزامی	توضیحات
`refreshToken`	string	الزامی	رمزینهٔ تازه‌سازی دریافت‌شده از پاسخ ورود یا تازه‌سازی پیشین.

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

200رمزینه‌ها با موفقیت تازه شدند

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...(new)",
    "refreshToken": "dGhpcyBpcyBhIG5ldyBy...(new)",
    "expiresAt": "2026-02-09T12:00:00Z",
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "role": "user"
    }
  }
}

401رمزینهٔ تازه‌سازی منقضی یا نامعتبر

{
  "success": false,
  "error": {
    "code": "INVALID_REFRESH_TOKEN",
    "message": "The refresh token is expired or has been revoked. Please log in again."
  }
}

چرخش رمزینهٔ تازه‌سازی

هر فراخوان نقطهٔ پایانی تازه‌سازی، رمزینهٔ تازه‌سازی تازه‌ای برمی‌گرداند و قبلی را بی‌اعتبار می‌کند. به این چرخش رمزینهٔ تازه‌سازی می‌گویند و جلوی حمله‌های بازپخش رمزینه را می‌گیرد. همیشه تازه‌ترین رمزینهٔ تازه‌سازی را نگه دارید و به کار ببرید.

خروج

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

POST/api/v1/auth/logout

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

احراز هویت:توکن Bearer

پارامتر	نوع	الزامی	توضیحات
`refreshToken`	string	الزامی	رمزینهٔ تازه‌سازی‌ای که باید باطل شود.

curl -X POST https://api.orbai.world/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2..."
  }'

200خروج موفق

{
  "success": true,
  "data": {
    "message": "Successfully logged out."
  }
}

ثبت‌نام کاربر

با ایمیل و گذرواژه حساب تازه‌ای در OrbVPN بسازید. حساب‌های تازه پیش از دریافت دسترسی کامل API به تأیید ایمیل نیاز دارند.

POST/api/v1/auth/register

حساب کاربری تازه‌ای با ایمیل، گذرواژه و نام نمایشی ثبت کنید.

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

پارامتر	نوع	الزامی	توضیحات
`email`	string	الزامی	نشانی ایمیل معتبر. نباید از پیش ثبت شده باشد.
`password`	string	الزامی	گذرواژه با کمینه ۸ نویسه، شامل حرف بزرگ، حرف کوچک و رقم.
`name`	string	الزامی	نام نمایشی کاربر.

curl -X POST https://api.orbai.world/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "SecureP@ss123",
    "name": "Jane Doe"
  }'

201حساب با موفقیت ساخته شد

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2...",
    "expiresAt": "2026-02-08T12:00:00Z",
    "user": {
      "id": "usr_def456",
      "email": "newuser@example.com",
      "role": "user"
    },
    "emailVerificationRequired": true
  }
}

409ایمیل از پیش ثبت شده است

{
  "success": false,
  "error": {
    "code": "EMAIL_EXISTS",
    "message": "An account with this email address already exists."
  }
}

تأیید ایمیل

پس از ثبت‌نام، ایمیل تأیید خودکار فرستاده می‌شود. کاربر باید روی پیوند تأیید بزند یا کد را وارد کند تا حسابش فعال شود. برخی نقاط پایانی محافظت‌شده تا کامل شدن تأیید ممکن است دادهٔ محدودی برگردانند.

ورود اجتماعی OAuth2

به کاربران امکان دهید با حساب موجود گوگل یا اپل خود احراز هویت شوند. کلاینت رمزینهٔ OAuth را از ارائه‌دهندهٔ هویت می‌گیرد، سپس آن را با OrbNET برای جفت رمزینهٔ JWT مبادله می‌کند.

OAuth گوگل

POST/api/v1/auth/oauth/google

با رمزینهٔ شناسایی OAuth2 گوگل احراز هویت کنید.

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

پارامتر	نوع	الزامی	توضیحات
`idToken`	string	الزامی	رمزینهٔ شناسایی گوگل که از Google Sign-In روی کلاینت گرفته می‌شود.

curl -X POST https://api.orbai.world/api/v1/auth/oauth/google \
  -H "Content-Type: application/json" \
  -d '{
    "idToken": "eyJhbGciOiJSUzI1NiIs...(Google ID token)"
  }'

200OAuth گوگل موفق بود

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2...",
    "expiresAt": "2026-02-08T12:00:00Z",
    "user": {
      "id": "usr_ggl789",
      "email": "user@gmail.com",
      "role": "user"
    },
    "isNewUser": false
  }
}

OAuth اپل

POST/api/v1/auth/oauth/apple

با کد مجوز Apple Sign-In احراز هویت کنید.

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

پارامتر	نوع	الزامی	توضیحات
`authorizationCode`	string	الزامی	کد مجوز از Apple Sign-In.
`identityToken`	string	الزامی	رمزینهٔ هویت از Apple Sign-In.
`name`	string	اختیاری	نام کامل کاربر (تنها در نخستین ورود با اپل داده می‌شود).

curl -X POST https://api.orbai.world/api/v1/auth/oauth/apple \
  -H "Content-Type: application/json" \
  -d '{
    "authorizationCode": "c1a2b3d4e5f6...",
    "identityToken": "eyJhbGciOiJSUzI1NiIs...",
    "name": "Jane Doe"
  }'

200OAuth اپل موفق بود

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2...",
    "expiresAt": "2026-02-08T12:00:00Z",
    "user": {
      "id": "usr_apl012",
      "email": "user@privaterelay.appleid.com",
      "role": "user"
    },
    "isNewUser": true
  }
}

جریان رمزینهٔ OAuth

هر دو نقطهٔ پایانی OAuth گوگل و اپل در نخستین استفاده حساب تازه‌ای در OrbVPN می‌سازند (با isNewUser: true نشان داده می‌شود) و ورودهای بعدی را به همان حساب پیوند می‌زنند. رمزینه‌های JWT برگشتی دقیقاً مانند رمزینه‌های ورود با ایمیل و گذرواژه کار می‌کنند.

کلیدگذر / WebAuthn

احراز هویت بدون گذرواژه با استاندارد FIDO2/WebAuthn. از کلیدهای امنیتی سخت‌افزاری، زیست‌سنجی سکو (Touch ID، Face ID، Windows Hello) و احراز هویت میان‌دستگاهی پشتیبانی می‌کند. این جریان دو رفت‌وبرگشت می‌خواهد: فراخوان begin برای گرفتن چالش از سرور، و پس از آن فراخوان finish با چالش امضاشده از احرازکننده.

مقاوم در برابر فیشینگ

کلیدگذرها به دامنهٔ مبدأ گره خورده‌اند و روی سایت‌های تقلبی قابل استفاده نیستند.

احراز هویت سریع

ورود زیستی با یک ضربه، بدون تایپ گذرواژه یا انتظار برای کد.

بدون راز مشترک

کلیدهای خصوصی هرگز دستگاه احرازکننده را ترک نمی‌کنند. سرور تنها کلیدهای عمومی را نگه می‌دارد.

ثبت یک کلیدگذر

گام ۱: آغاز ثبت

POST/api/v1/auth/passkeys/register/begin

چالش ثبت WebAuthn را از سرور درخواست کنید.

احراز هویت:توکن Bearer

curl -X POST https://api.orbai.world/api/v1/auth/passkeys/register/begin \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

200چالش ثبت ساخته شد

{
  "success": true,
  "data": {
    "publicKey": {
      "challenge": "dGhpcyBpcyBhIGNoYWxsZW5nZQ...",
      "rp": { "name": "OrbVPN", "id": "orbvpn.com" },
      "user": {
        "id": "dXNyX2FiYzEyMw...",
        "name": "user@example.com",
        "displayName": "Jane Doe"
      },
      "pubKeyCredParams": [
        { "type": "public-key", "alg": -7 },
        { "type": "public-key", "alg": -257 }
      ],
      "timeout": 60000,
      "attestation": "none",
      "authenticatorSelection": {
        "residentKey": "preferred",
        "userVerification": "preferred"
      }
    }
  }
}

گام ۲: پایان ثبت

POST/api/v1/auth/passkeys/register/finish

با فرستادن گواهی امضاشده از احرازکننده، ثبت کلیدگذر را کامل کنید.

احراز هویت:توکن Bearer

پارامتر	نوع	الزامی	توضیحات
`credential`	object	الزامی	شیء PublicKeyCredential که navigator.credentials.create() برمی‌گرداند، سریال‌شده به JSON.

curl -X POST https://api.orbai.world/api/v1/auth/passkeys/register/finish \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "id": "a1b2c3d4e5...",
      "rawId": "YTFiMmMzZDRl...",
      "type": "public-key",
      "response": {
        "attestationObject": "o2NmbXRk...",
        "clientDataJSON": "eyJ0eXBlI..."
      }
    }
  }'

200کلیدگذر با موفقیت ثبت شد

{
  "success": true,
  "data": {
    "credentialId": "a1b2c3d4e5...",
    "message": "Passkey registered successfully."
  }
}

احراز هویت با کلیدگذر

گام ۱: آغاز ورود

POST/api/v1/auth/passkeys/login/begin

چالش احراز هویت WebAuthn را درخواست کنید.

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

پارامتر	نوع	الزامی	توضیحات
`email`	string	اختیاری	اختیاری. ایمیل کاربر برای باریک کردن انتخاب گواهی.

curl -X POST https://api.orbai.world/api/v1/auth/passkeys/login/begin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

200چالش احراز هویت ساخته شد

{
  "success": true,
  "data": {
    "publicKey": {
      "challenge": "YW5vdGhlciBjaGFsbGVuZ2U...",
      "timeout": 60000,
      "rpId": "orbvpn.com",
      "allowCredentials": [
        {
          "type": "public-key",
          "id": "a1b2c3d4e5..."
        }
      ],
      "userVerification": "preferred"
    }
  }
}

گام ۲: پایان ورود

POST/api/v1/auth/passkeys/login/finish

با فرستادن ادعای امضاشده، احراز هویت کلیدگذر را کامل کنید.

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

پارامتر	نوع	الزامی	توضیحات
`credential`	object	الزامی	شیء PublicKeyCredential که navigator.credentials.get() برمی‌گرداند، سریال‌شده به JSON.

curl -X POST https://api.orbai.world/api/v1/auth/passkeys/login/finish \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "id": "a1b2c3d4e5...",
      "rawId": "YTFiMmMzZDRl...",
      "type": "public-key",
      "response": {
        "authenticatorData": "SZYN5YgO...",
        "clientDataJSON": "eyJ0eXBlI...",
        "signature": "MEUCIQC...",
        "userHandle": "dXNyX2FiYzEyMw..."
      }
    }
  }'

200احراز هویت کلیدگذر موفق بود

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2...",
    "expiresAt": "2026-02-08T12:00:00Z",
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "role": "user"
    }
  }
}

گواهی‌های قابل کشف

اگر در گام آغاز ایمیلی داده نشود، مرورگر همهٔ گواهی‌های قابل کشف (کلیدهای مقیم) آن دامنه را نمایش می‌دهد. این تجربه‌ای واقعاً بدون گذرواژه و بدون نام کاربری را ممکن می‌کند.

پیوندهای جادویی

پیوند ورود یک‌بارمصرفی به ایمیل کاربر بفرستید. زدن روی پیوند کاربر را احراز هویت می‌کند و رمزینه‌های JWT برمی‌گرداند. نیازی به گذرواژه نیست. اگر احراز هویت دوعاملی برای حساب روشن باشد، پیوند به‌تنهایی کافی نیست: راستی‌آزمایی آن چالش requires_2fa برمی‌گرداند و کاربر با کد خود ورود را کامل می‌کند.

فرستادن پیوند جادویی

POST/api/v1/auth/magic-link/request

پیوند ورود جادویی یک‌بارمصرفی به نشانی ایمیل مشخص‌شده بفرستید.

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

پارامتر	نوع	الزامی	توضیحات
`email`	string	الزامی	نشانی ایمیلی که پیوند جادویی به آن فرستاده می‌شود. باید حسابی ثبت‌شده باشد.

curl -X POST https://api.orbai.world/api/v1/auth/magic-link/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

200پیوند جادویی فرستاده شد

{
  "success": true,
  "data": {
    "message": "A magic link has been sent to your email address.",
    "expiresIn": 600
  }
}

هشدار امنیتی

پیوندهای جادویی پس از ۱۰ دقیقه منقضی می‌شوند و تنها یک بار قابل استفاده‌اند. برای امنیت، API همیشه پاسخ موفق برمی‌گرداند، فارغ از اینکه ایمیل ثبت شده باشد یا نه، تا جلوی برشماری حساب‌ها گرفته شود.

راستی‌آزمایی پیوند جادویی

وقتی کاربر روی پیوند جادویی در ایمیل خود می‌زند، با پارامتر پرس‌وجوی token به اپلیکیشن شما هدایت می‌شود. این رمزینه را با گواهی‌های JWT مبادله کنید.

POST/api/v1/auth/magic-link/verify

رمزینهٔ پیوند جادویی را راستی‌آزمایی کنید و گواهی‌های JWT را بگیرید؛ یا اگر احراز هویت دوعاملی برای حساب روشن است، چالش requires_2fa را.

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

پارامتر	نوع	الزامی	توضیحات
`token`	string	الزامی	رمزینهٔ یک‌بارمصرف از پارامتر پرس‌وجوی نشانی پیوند جادویی.
`device_id`	string	اختیاری	شناسهٔ پایدار دستگاه برای نشست دستگاه (در سقف دستگاه‌های طرح شمرده می‌شود). برای نشست مرورگر بدون مصرف جای دستگاه، به‌جای آن platform را web بفرستید.
`platform`	string	اختیاری	یکی از: ios، android، windows، macos، linux، web.
`device_name`	string	اختیاری	نام خوانای دستگاه.

curl -X POST https://api.orbai.world/api/v1/auth/magic-link/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "ml_abc123def456...", "platform": "web"}'

200پیوند راستی‌آزمایی شد؛ حساب احراز هویت دوعاملی ندارد

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "role": "USER"
    },
    "tokens": {
      "access_token": "eyJhbGciOiJIUzI1NiIs...",
      "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2...",
      "access_token_expires_at": "2026-02-08T12:00:00Z",
      "refresh_token_expires_at": "2026-03-08T12:00:00Z",
      "token_type": "Bearer"
    }
  }
}

200پیوند راستی‌آزمایی شد؛ حساب احراز هویت دوعاملی دارد و هنوز رمزینه‌ای صادر نمی‌شود

{
  "success": true,
  "data": {
    "requires_2fa": true,
    "user": {
      "email": "user@example.com"
    },
    "two_factor": {
      "pending_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_in": 300,
      "methods": ["totp", "recovery_code"]
    }
  }
}

401رمزینهٔ پیوند جادویی منقضی یا نامعتبر است

{
  "success": false,
  "error": {
    "code": "INVALID_MAGIC_LINK",
    "message": "This magic link has expired or has already been used."
  }
}

پیوند فقط با پایان ورود مصرف می‌شود

وقتی کد لازم است، پیوند جادویی در مرحلهٔ راستی‌آزمایی مصرف نمی‌شود. پیوند هنگام موفقیت POST /api/v1/auth/2fa/complete مصرف می‌شود؛ پس کاربری که صفحهٔ کد را می‌بندد، تا زمانی که پیوند معتبر است می‌تواند دوباره از همان پیوند استفاده کند. هر پیوند فقط یک بار به ورود می‌انجامد، حتی اگر دو بار راستی‌آزمایی شده باشد.

احراز هویت دوعاملی (2FA)

با گذرواژه‌های یک‌بارمصرف مبتنی بر زمان (TOTP) لایهٔ دوم راستی‌آزمایی بیفزایید. با اپ‌های احرازکننده مانند Google Authenticator، Authy و 1Password سازگار است.

وقتی 2FA روشن است، هر روش ورود کد را می‌خواهد: ورود با گذرواژه، پیوند جادویی، ورود با Google و Apple، کلید عبور (passkey) بدون تأیید کاربر، و مینی‌اپ تلگرام. کلید عبوری که کاربر را تأیید کرده باشد (زیست‌سنجی یا PIN) خودش دوعاملی به شمار می‌آید. ورود با QR که از تلفنی واردشده تأیید شود نیز همین‌طور است.

مدیریت 2FA

نقاط پایانی مدیریت به کاربر واردشده (رمزینهٔ Bearer) نیاز دارند. جزئیات کامل در مرجع احراز هویت دوعاملی آمده است.

نقطهٔ پایانی	بدنه	کاربرد
`POST /api/v1/security/totp/setup`	ندارد	`secret`، `qr_code_url` و `recovery_codes` را برمی‌گرداند. 2FA هنوز روشن نیست.
`POST /api/v1/security/totp/enable`	`{"code": "123456"}`	پس از نخستین کد درست اپ احرازکننده، 2FA را روشن می‌کند.
`POST /api/v1/security/totp/disable`	`{"code": "123456"}`	2FA را خاموش می‌کند.
`POST /api/v1/security/totp/recovery-codes`	`{"totp_code": "123456"}`	مجموعهٔ تازه‌ای از کدهای بازیابی صادر و کدهای پیشین را باطل می‌کند.

کدهای بازیابی را امن نگه دارید

کدهای بازیابی فقط یک بار نشان داده می‌شوند. هر کد یک بار، به‌جای کد اپ احرازکننده، کار می‌کند.

ورود هنگامی که 2FA روشن است

ورودی که عامل نخست آن درست است اما هنوز کد را بدهکار است، پاسخ HTTP 200 با یک چالش و بدون رمزینه برمی‌گرداند:

{
  "success": true,
  "data": {
    "requires_2fa": true,
    "user": { "email": "user@example.com" },
    "two_factor": {
      "pending_token": "eyJhbGciOiJIUzI1NiIs...",
      "expires_in": 300,
      "methods": ["totp", "recovery_code"]
    }
  }
}

کد را از کاربر بخواهید و همراه رمزینهٔ موقت بفرستید:

POST/api/v1/auth/2fa/complete

ورودی را که پاسخ requires_2fa داده کامل می‌کند. همان AuthResponse را برمی‌گرداند که روش ورود اصلی برمی‌گرداند.

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

پارامتر	نوع	الزامی	توضیحات
`pending_token`	string	الزامی	مقدار two_factor.pending_token از چالش. ۳۰۰ ثانیه اعتبار دارد و فقط یک ورود را کامل می‌کند.
`code`	string	الزامی	کد ۶ رقمی اپ احرازکننده، یا یک کد بازیابی (xxxx-xxxxxx). هر کد بازیابی فقط یک بار کار می‌کند.

curl -X POST https://api.orbai.world/api/v1/auth/2fa/complete \
  -H "Content-Type: application/json" \
  -d '{"pending_token": "eyJhbGciOiJIUzI1NiIs...", "code": "123456"}'

HTTP	`code`	کاری که کلاینت باید بکند
200	ندارد	ورود انجام شد. بدنه همان AuthResponse معمول است (`user`، `tokens`، `subscription`).
401	`TWO_FACTOR_INVALID`	کد نادرست است. رمزینهٔ موقت را نگه دارید و دوباره بپرسید.
429	`TWO_FACTOR_LOCKED`	بیش از ۵ تلاش در ۱۰ دقیقه برای این حساب. صبر کنید و دوباره تلاش کنید.
401	`TWO_FACTOR_PENDING_INVALID`	رمزینهٔ موقت منقضی، پیش‌تر استفاده‌شده یا نامعتبر است، یا حساب پس از صدور آن تغییر کرده است (بازنشانی رمز عبور، تصاحب حسابی که فروشنده ساخته است، یا خاموش‌شدن احراز هویت دومرحله‌ای). ورود را از نو آغاز کنید.
413	`PAYLOAD_TOO_LARGE`	بدنه بزرگ‌تر از ۱۶ کیلوبایت است. فقط `pending_token` و `code` را بفرستید.
422	`VALIDATION_ERROR`	`pending_token` یا `code` نیامده، `pending_token` بلندتر از ۸۱۹۲ نویسه است، یا `code` بین ۶ تا ۶۴ نویسه نیست.
403	`DEVICE_LIMIT_EXCEEDED`	ورود با دستگاه در حالی که همهٔ جای دستگاه‌ها پر است. با `device_logout_token` یک دستگاه را آزاد کنید، سپس همان رمزینهٔ موقت را با یک کد معتبر دوباره بفرستید.

خطاها در قالب RFC 7807 Problem Details (application/problem+json) هستند؛ فیلد code را بخوانید.

یک درخواست به‌جای دو درخواست، برای ورود با گذرواژه

ورود با گذرواژه کد را مستقیم هم می‌پذیرد: email، password و totp_code را به POST /api/v1/auth/login بفرستید. totp_code نادرست پاسخ 401 TWO_FACTOR_INVALID می‌دهد و همان سقف ۵ تلاش اعمال می‌شود.

رمزینهٔ موقت رمزینهٔ دسترسی نیست

API رمزینهٔ موقت را در هیچ مسیر احراز هویت‌شده‌ای به‌عنوان رمزینهٔ Bearer نمی‌پذیرد. این رمزینه هیچ دادهٔ حسابی ندارد و فقط در POST /api/v1/auth/2fa/complete کار می‌کند.

احراز هویت با کلید API

برای یکپارچگی‌های سرور به سرور، به‌ویژه با API آزمایشگاه OrbGuard، می‌توانید به‌جای رمزینه‌های JWT از کلیدهای ایستای API استفاده کنید. کلیدهای API از داشبورد OrbVPN ساخته می‌شوند و تا وقتی باطل نشوند منقضی نمی‌گردند.

ANY/api/v1/guard/*

نقاط پایانی OrbGuard Labs احراز هویت با کلید API را از راه سرآیند X-API-Key می‌پذیرند.

احراز هویت:کلید API

curl https://guard.orbai.world/api/v1/intelligence/check \
  -H "X-API-Key: orbk_live_abc123def456ghi789..."  \
  -H "Content-Type: application/json" \
  -d '{
    "indicator": "suspicious-domain.com",
    "type": "domain"
  }'

امنیت کلید API

کلیدهای API همهٔ مجوزهای حسابی را که ساخته‌شان دارند. هرگز کلیدهای API را در کد سمت کلاینت، اپ‌های همراه یا مخازن عمومی جاسازی نکنید. برای ذخیره‌سازی سمت سرور از متغیرهای محیطی یا مدیر رازها استفاده کنید. کلیدها را مرتب از داشبورد OrbVPN بچرخانید.

بهترین شیوه‌های امنیتی

همه‌جا از HTTPS استفاده کنید

همهٔ درخواست‌های API باید HTTPS باشند. درخواست‌های HTTP رد می‌شوند. برای همهٔ اتصال‌ها به سکوی OrbNET نسخهٔ TLS 1.2 یا بالاتر لازم است.

رمزینه‌ها را امن نگه دارید

از کوکی‌های HTTP-only، کیف کلید سکو یا ذخیره‌سازی رمزنگاری‌شده استفاده کنید. هرگز رمزینه‌ها را در localStorage اپ‌های وب نگه ندارید و در نشانی‌ها جاسازی نکنید.

تازه‌سازی رمزینه را پیاده کنید

منطق تازه‌سازی خودکار رمزینه را در کلاینت خود بسازید. با دریافت ۴۰۱، پیش از خواستن احراز هویت دوباره از کاربر، تازه‌سازی بی‌صدا را امتحان کنید.

برای حساب‌های حساس احراز هویت دوعاملی بگذارید

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

کلیدهای API را بچرخانید

کلیدهای API را به‌صورت دوره‌ای از داشبورد بچرخانید. هر کلیدی را که ممکن است فاش شده باشد باطل کنید. برای توسعه و تولید کلیدهای جداگانه به کار ببرید.

مراقب ناهنجاری‌ها باشید

مراقب الگوهای غیرعادی احراز هویت باشید، مانند ورود از موقعیت‌های تازه، تازه‌سازی‌های پرشتاب رمزینه یا نشست‌های هم‌زمان از مناطق گوناگون.

مرجع خطاها

کدهای رایج خطای احراز هویت و شیوهٔ رسیدگی به آن‌ها.

INVALID_CREDENTIALS

ایمیل یا گذرواژه نادرست است. از کاربر بخواهید گواهی‌های خود را بررسی کند و دوباره تلاش کند.

TOKEN_EXPIRED

رمزینهٔ دسترسی منقضی شده است. با رمزینهٔ تازه‌سازی رمزینهٔ دسترسی تازه‌ای بگیرید.

INVALID_REFRESH_TOKEN

رمزینهٔ تازه‌سازی منقضی یا باطل شده است. کاربر باید دوباره با گواهی‌های خود وارد شود.

requires_2fa

خطا نیست: پاسخ 200 بدون رمزینه. این حساب احراز هویت دوعاملی فعال دارد. رمزینهٔ موقت و کد کاربر را به POST /api/v1/auth/2fa/complete بفرستید.

TWO_FACTOR_INVALID

کد اپ احرازکننده یا کد بازیابی نادرست است (401). رمزینهٔ موقت را نگه دارید و دوباره از کاربر بپرسید.

TWO_FACTOR_LOCKED

کدهای نادرست بیش از حد برای این حساب (429): حداکثر ۵ تلاش در ۱۰ دقیقه. پیش از تلاش دوباره صبر کنید.

TWO_FACTOR_PENDING_INVALID

رمزینهٔ موقت منقضی شده (پس از ۵ دقیقه)، پیش‌تر استفاده شده، نامعتبر است یا پیش از بازنشانی رمز عبور، تصاحب حسابی که فروشنده ساخته است، یا خاموش‌شدن احراز هویت دومرحله‌ای صادر شده است (401). ورود را از نو آغاز کنید.

EMAIL_NOT_VERIFIED

حساب وجود دارد اما ایمیل تأیید نشده است. کاربر را به جریان تأیید هدایت کنید.

RATE_LIMITED

تلاش‌های بیش‌ازحد برای احراز هویت. پیش از تلاش دوباره مقدار retryAfter در پاسخ خطا را رعایت کنید.

ACCOUNT_LOCKED

این حساب به دلیل فعالیت مشکوک موقتاً قفل شده است. با پشتیبانی تماس بگیرید یا منتظر پایان دورهٔ قفل بمانید.

INVALID_API_KEY

کلید API داده‌شده نامعتبر، منقضی یا باطل است. کلید تازه‌ای از داشبورد OrbVPN بسازید.

کمک لازم دارید؟

اگر با مشکل احراز هویت روبه‌رو هستید، راهنمای عیب‌یابی ما را ببینید یا با پشتیبانی توسعه‌دهندگان تماس بگیرید. برای مشکل‌های ویژهٔ حساب، به درگاه پشتیبانی سر بزنید.

ساختن با OrbNET را آغاز کنید

اکنون آمادهٔ احراز هویت و فرستادن درخواست‌های امن API هستید. مرجع کامل API اوربنت را کاوش کنید تا اتصال‌های VPN، کاربران، اشتراک‌ها و بیشتر را مدیریت کنید.

کاوش API اوربنت

احراز هویت

احراز هویت

نمای کلی روش‌های احراز هویت

رمزینه‌های حامل JWT

ورود اجتماعی OAuth2

کلیدگذر / WebAuthn

پیوندهای جادویی

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

احراز هویت با کلید API

جریان احراز هویت

گواهی‌ها را بگیرید

احراز هویت کنید

رمزینه را در درخواست‌ها بگنجانید

پس از انقضا تازه کنید

احراز هویت با رمزینهٔ حامل JWT

ورود

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

استفاده از رمزینهٔ دسترسی

امنیت رمزینه

تازه‌سازی رمزینه‌ها

چرخش رمزینهٔ تازه‌سازی

خروج

ثبت‌نام کاربر

تأیید ایمیل

ورود اجتماعی OAuth2

OAuth گوگل

OAuth اپل

جریان رمزینهٔ OAuth

کلیدگذر / WebAuthn

مقاوم در برابر فیشینگ

احراز هویت سریع

بدون راز مشترک

ثبت یک کلیدگذر

گام ۱: آغاز ثبت

گام ۲: پایان ثبت

احراز هویت با کلیدگذر

گام ۱: آغاز ورود

گام ۲: پایان ورود

گواهی‌های قابل کشف

پیوندهای جادویی

فرستادن پیوند جادویی

هشدار امنیتی

راستی‌آزمایی پیوند جادویی

پیوند فقط با پایان ورود مصرف می‌شود

احراز هویت دوعاملی (2FA)

مدیریت 2FA

کدهای بازیابی را امن نگه دارید

ورود هنگامی که 2FA روشن است

یک درخواست به‌جای دو درخواست، برای ورود با گذرواژه

رمزینهٔ موقت رمزینهٔ دسترسی نیست

احراز هویت با کلید API

امنیت کلید API

بهترین شیوه‌های امنیتی

همه‌جا از HTTPS استفاده کنید

رمزینه‌ها را امن نگه دارید

تازه‌سازی رمزینه را پیاده کنید

برای حساب‌های حساس احراز هویت دوعاملی بگذارید

کلیدهای API را بچرخانید

مراقب ناهنجاری‌ها باشید

مرجع خطاها

INVALID_CREDENTIALS

TOKEN_EXPIRED

INVALID_REFRESH_TOKEN

requires_2fa

TWO_FACTOR_INVALID

TWO_FACTOR_LOCKED

TWO_FACTOR_PENDING_INVALID

EMAIL_NOT_VERIFIED

RATE_LIMITED

ACCOUNT_LOCKED

INVALID_API_KEY

کمک لازم دارید؟

ساختن با OrbNET را آغاز کنید

در این صفحه