احراز هویت

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

امنیت

احراز هویت

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

شروع کار

0
روش احراز هویت
0
عمر رمزینه
0
پشتیبانی دوعاملی
0
استاندارد کلیدگذر

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

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

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

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

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

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

کلیدگذر / WebAuthn

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

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

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

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

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

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

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

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

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

1

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

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

2

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

نقطهٔ پایانی ورود را با گواهی‌های خود فراخوانی کنید. سرور رمزینهٔ دسترسی JWT و رمزینهٔ تازه‌سازی برمی‌گرداند.

3

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

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

4

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

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

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

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

ورود

POST/api/v1/auth/login

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

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
emailstring الزامینشانی ایمیل ثبت‌شدهٔ کاربر.
passwordstring الزامیگذرواژهٔ کاربر. کمینه ۸ نویسه.
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
    }
  }
}

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

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

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

امنیت رمزینه

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

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

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

POST/api/v1/auth/refresh

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

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
refreshTokenstring الزامیرمزینهٔ تازه‌سازی دریافت‌شده از پاسخ ورود یا تازه‌سازی پیشین.
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
پارامترنوعالزامیتوضیحات
refreshTokenstring الزامیرمزینهٔ تازه‌سازی‌ای که باید باطل شود.
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

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

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
emailstring الزامینشانی ایمیل معتبر. نباید از پیش ثبت شده باشد.
passwordstring الزامیگذرواژه با کمینه ۸ نویسه، شامل حرف بزرگ، حرف کوچک و رقم.
namestring الزامینام نمایشی کاربر.
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 گوگل احراز هویت کنید.

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
idTokenstring الزامیرمزینهٔ شناسایی گوگل که از 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 احراز هویت کنید.

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
authorizationCodestring الزامیکد مجوز از Apple Sign-In.
identityTokenstring الزامیرمزینهٔ هویت از Apple Sign-In.
namestringاختیارینام کامل کاربر (تنها در نخستین ورود با اپل داده می‌شود).
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
پارامترنوعالزامیتوضیحات
credentialobject الزامیشیء 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 را درخواست کنید.

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
emailstringاختیاریاختیاری. ایمیل کاربر برای باریک کردن انتخاب گواهی.
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

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

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
credentialobject الزامیشیء 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 برمی‌گرداند. نیازی به گذرواژه نیست.

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

POST/api/v1/auth/magic-link

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

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
emailstring الزامینشانی ایمیلی که پیوند جادویی به آن فرستاده می‌شود. باید حسابی ثبت‌شده باشد.
curl -X POST https://api.orbai.world/api/v1/auth/magic-link \
  -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 مبادله کنید.

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

رمزینهٔ پیوند جادویی را راستی‌آزمایی کنید و گواهی‌های JWT برگردانید.

احراز هویت:بدون احراز هویت
پارامترنوعالزامیتوضیحات
tokenstring الزامیرمزینهٔ یک‌بارمصرف از پارامتر پرس‌وجوی نشانی پیوند جادویی.
curl "https://api.orbai.world/api/v1/auth/magic-link/verify?token=ml_abc123def456..."
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_MAGIC_LINK",
    "message": "This magic link has expired or has already been used."
  }
}

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

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

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

POST/api/v1/auth/2fa/enable

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

احراز هویت:توکن Bearer
curl -X POST https://api.orbai.world/api/v1/auth/2fa/enable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
200راه‌اندازی TOTP آغاز شد
{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCodeUri": "otpauth://totp/OrbVPN:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=OrbVPN&algorithm=SHA1&digits=6&period=30",
    "recoveryCodes": [
      "abc12-def34",
      "ghi56-jkl78",
      "mno90-pqr12",
      "stu34-vwx56",
      "yza78-bcd90",
      "efg12-hij34",
      "klm56-nop78",
      "qrs90-tuv12"
    ]
  }
}

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

کدهای بازیابی تنها یک بار نشان داده می‌شوند. به کاربران بگویید آن‌ها را در جایی امن ذخیره کنند. اگر کاربری دسترسی به اپ احرازکننده و کدهای بازیابی خود را از دست بدهد، برای بازپس‌گیری دسترسی به حسابش باید با پشتیبانی تماس بگیرد.

راستی‌آزمایی کد دوعاملی

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

POST/api/v1/auth/2fa/verify

کد TOTP را راستی‌آزمایی کنید تا راه‌اندازی دوعاملی کامل شود یا چالش ورود دوعاملی پاسخ بگیرد.

احراز هویت:توکن Bearer
پارامترنوعالزامیتوضیحات
codestring الزامیکد ۶ رقمی TOTP از اپ احرازکننده.
curl -X POST https://api.orbai.world/api/v1/auth/2fa/verify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'
200راستی‌آزمایی دوعاملی موفق بود
{
  "success": true,
  "data": {
    "message": "Two-factor authentication verified successfully.",
    "twoFactorEnabled": true
  }
}
401کد TOTP نامعتبر
{
  "success": false,
  "error": {
    "code": "INVALID_2FA_CODE",
    "message": "The verification code is incorrect or has expired."
  }
}

غیرفعال کردن احراز هویت دوعاملی

POST/api/v1/auth/2fa/disable

احراز هویت دوعاملی را برای کاربر کنونی غیرفعال کنید.

احراز هویت:توکن Bearer
پارامترنوعالزامیتوضیحات
codestring الزامیکد معتبر ۶ رقمی TOTP برای تأیید این کار.
passwordstring الزامیگذرواژهٔ کنونی کاربر برای راستی‌آزمایی افزوده.
curl -X POST https://api.orbai.world/api/v1/auth/2fa/disable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "654321",
    "password": "your_password"
  }'
200احراز هویت دوعاملی با موفقیت غیرفعال شد
{
  "success": true,
  "data": {
    "message": "Two-factor authentication has been disabled.",
    "twoFactorEnabled": false
  }
}

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

وقتی کاربری با احراز هویت دوعاملی فعال POST /api/v1/auth/login را فراخوانی کند، پاسخ شامل "twoFactorRequired": true و رمزینه‌ای موقت با دامنهٔ محدود خواهد بود. سپس کلاینت باید POST /api/v1/auth/2fa/verify را با آن رمزینه و کد TOTP فراخوانی کند تا رمزینه‌های کامل دسترسی و تازه‌سازی را بگیرد.

احراز هویت با کلید 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

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

TWO_FACTOR_REQUIRED

این حساب احراز هویت دوعاملی فعال دارد. برای کامل کردن ورود، کد TOTP را به نقطهٔ پایانی راستی‌آزمایی دوعاملی بفرستید.

EMAIL_NOT_VERIFIED

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

RATE_LIMITED

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

ACCOUNT_LOCKED

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

INVALID_API_KEY

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

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

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

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

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

کاوش API اوربنت

در این صفحه

نمای کلی روش‌های احراز هویت
جریان احراز هویت
احراز هویت با رمزینهٔ حامل JWT
ورود
استفاده از رمزینهٔ دسترسی
تازه‌سازی رمزینه‌ها
خروج
ثبت‌نام کاربر
ورود اجتماعی OAuth2
OAuth گوگل
OAuth اپل
کلیدگذر / WebAuthn
ثبت یک کلیدگذر
گام ۱: آغاز ثبت
گام ۲: پایان ثبت
احراز هویت با کلیدگذر
گام ۱: آغاز ورود
گام ۲: پایان ورود
پیوندهای جادویی
فرستادن پیوند جادویی
راستی‌آزمایی پیوند جادویی
احراز هویت دوعاملی (2FA)
فعال کردن احراز هویت دوعاملی
راستی‌آزمایی کد دوعاملی
غیرفعال کردن احراز هویت دوعاملی
احراز هویت با کلید API
بهترین شیوه‌های امنیتی
مرجع خطاها