3x-ui3x-ui
مرجعمرجع API

احراز هویت

دو حالت احراز هویت پشتیبانی می‌شود. نشست‌های UI از یک کوکی استفاده می‌کنند که توسط نقطه‌پایانی ورود تنظیم می‌شود. کلاینت‌های برنامه‌نویسی‌شده (ربات‌ها، اسکریپت‌ها، پنل‌های راه دور) با یک توکن Bearer که از مسیر Settings → Security → API Token گرفته می‌شود احراز هویت می‌کنند. هر دو روش برای همهٔ نقاط‌پایانی زیر /panel/api/* کار می‌کنند.

Authenticate with username + password and receive a session cookie. Required before any cookie-based API call.

POST
/login

Authorization

headerAuthorizationBearer <token>

Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

Request Body

application/json
  1. body
username*string

Panel admin username.

password*string

Panel admin password.

twoFactorCode?string

OTP code when 2FA is enabled. Omit otherwise.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/login" \  -H "Content-Type: application/json" \  -d '{    "username": "admin",    "password": "admin",    "twoFactorCode": "123456"  }'
{  "success": true,  "msg": "Logged in successfully"}
POST
/logout

Authorization

headerAuthorizationBearer <token>

Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/logout"
{  "success": true}

Mint a CSRF token for the current session. The SPA replays it in the X-CSRF-Token header on unsafe requests. Bearer-token callers can skip this — the middleware short-circuits CSRF for authenticated API requests.

GET
/csrf-token

Authorization

headerAuthorizationBearer <token>

Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X GET "https://example.com/csrf-token"
{  "success": true,  "obj": "csrf-token-string"}

Returns whether 2FA is enabled on the panel — used by the login page to decide whether to show the OTP field.

POST
/getTwoFactorEnable

Authorization

headerAuthorizationBearer <token>

Scoped API token from Settings → Security → API Token. Send as Authorization: Bearer <token>.

Response Body

Successful response

application/json
  1. response
success?boolean
msg?string
obj?unknown
curl -X POST "https://example.com/getTwoFactorEnable"
{  "success": true,  "obj": false}

مرجع API

REST API پنل 3x-ui — احراز هویت، inboundها، کلاینت‌ها، آمار سرور و موارد دیگر، تولیدشده از مشخصات OpenAPI.

توکن‌های API

مدیریت توکن‌های Bearer برای احراز هویت برنامه‌نویسی‌شده (ربات‌ها، پنل‌های مرکزی که از طرف این نود عمل می‌کنند، CI). هر توکن یک نام یکتا و یک پرچم فعال‌سازی دارد — برای لغو بدون حذف، آن را غیرفعال کنید و برای لغو دائمی، آن را حذف کنید. توکن‌ها به صورت هش SHA-256 ذخیره می‌شوند و متن خام تنها یک‌بار، در پاسخ ایجاد، بازگردانده می‌شود — پس از آن قابل بازیابی نیست، بنابراین همان موقع آن را کپی کنید. برای هر درخواست /panel/api/* یکی را به صورت <code>Authorization: Bearer &lt;token&gt;</code> ارسال کنید — این توکن یک اعتبارنامهٔ مدیر کامل است.