flvx/skills/flvx-api/references/auth.md

Authentication API

POST /api/v1/user/login

Authenticate and obtain JWT token.

Request:

{
  "username": "admin",
  "password": "secret",
  "captchaId": "optional-captcha-id"
}

Response:

{
  "code": 0,
  "msg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "name": "Administrator",
    "role_id": 0,
    "requirePasswordChange": false
  },
  "ts": 1706659200000
}

Response Fields:

Field	Type	Description
token	string	JWT token for subsequent requests
name	string	User's display name
role_id	number	0 = admin, 1 = regular user
requirePasswordChange	boolean	Whether password change is required

JWT Token Details

Algorithm: HMAC-SHA256 Lifetime: 90 days

Token Claims:

{
  "sub": "1",
  "user": "admin",
  "name": "Administrator",
  "role_id": 0,
  "iat": 1706659200,
  "exp": 1738195200
}

POST /api/v1/captcha/check

Check if captcha verification is required.

Request: {}

Response:

{
  "code": 0,
  "data": {
    "enabled": true,
    "type": "turnstile"
  }
}

POST /api/v1/captcha/verify

Verify captcha response (Cloudflare Turnstile or local captcha).

Request:

{
  "captchaId": "captcha-session-id",
  "captchaValue": "user-captcha-response"
}

Token Usage

Include the token in all authenticated requests:

curl -X POST "${FLVX_BASE_URL}/api/v1/node/list" \
  -H "Authorization: eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{}'

⚠️ CRITICAL: Do NOT add "Bearer " prefix!

✅ Correct:   Authorization: eyJhbGciOiJIUzI1NiIs...
❌ Incorrect: Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

POST /api/v1/user/updatePassword

Change current user's password.

Request:

{
  "oldPassword": "current-password",
  "newPassword": "new-password"
}

Response:

{"code": 0, "msg": "success"}

POST /api/v1/user/package

Get current user's package info (tunnels, forwards, traffic stats).

Request: {}

Response:

{
  "code": 0,
  "data": {
    "flow": 100,
    "inFlow": 1073741824,
    "outFlow": 2147483648,
    "tunnels": 5,
    "forwards": 10,
    "expTime": 1735689600000
  }
}

Fields:

Field	Type	Description
flow	number	Total traffic quota in GB
inFlow	number	Used upload in bytes
outFlow	number	Used download in bytes
tunnels	number	Number of assigned tunnels
forwards	number	Number of forwards created
expTime	number	Account expiry timestamp (ms)