3x-ui3x-ui

Authentication

Two authentication modes are supported. UI sessions use a cookie set by the login endpoint. Programmatic clients (bots, scripts, remote panels) authenticate with a Bearer token taken from Settings → Security → API Token. Both work for every endpoint under /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
Example Request
curl -X POST 'https://example.com/login' \  -H 'Content-Type: application/json' \  -d '{  "username": "admin",  "password": "admin",  "twoFactorCode": "123456"}'
Example Response
{  "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
Example Request
curl -X POST 'https://example.com/logout'
Example Response200
{  "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
Example Request
curl -X GET 'https://example.com/csrf-token'
Example Response200
{  "success": true,  "obj": "csrf-token-string"}

Public. Active paid sponsor placements read from the project sponsors.json (cached for 1h); entries outside their from/until window are dropped. Logos are proxied by the panel at /sponsors/logo/{name}. Used by the login page and panel sponsor slots.

GET
/sponsors

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?

SponsorList is the active sponsor set plus the contact link for new sponsors.

Example Request
curl -X GET 'https://example.com/sponsors'
Example Response200
{  "success": true,  "obj": {    "contact": "https://t.me/example",    "sponsors": [      {        "enable": true,        "from": "2026-10-01T00:00:00Z",        "id": "acme-2026-10",        "link": "https://acme.example/?utm_source=3x-ui",        "logo": "/sponsors/logo/acme.png",        "name": "Acme VPS",        "slots": [          ""        ],        "text": {},        "title": {},        "until": "2026-11-01T00:00:00Z"      }    ]  }}

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
Example Request
curl -X POST 'https://example.com/getTwoFactorEnable'
Example Response200
{  "success": true,  "obj": false}