Version 2.1.1792967583 · latest Download OpenAPI Markdown

Authentication

Login, token refresh, logout, password change, TOTP, password reset, captcha and admin SSO. Login endpoints need no authentication.

authAuthenticationAuthentication: No auth13 endpoints

Get captcha

GET/api/v2/auth/captcha

Authentication: No auth

Log in

POST/api/v2/auth/login

Authentication: No auth

Request body application/json

Field	Type	Required	Description
captcha_code	string	—	Characters shown in the captcha image
captcha_id	string	—	Captcha id from GET /auth/captcha; required after repeated failed logins
password	string	Required	Login password
totp_code	string	—	Current 6-digit TOTP code, or an unused recovery code (XXXXX-XXXXX, consumed on use); required when the account has TOTP enabled
username	string	Required	Username
verify_code	string	—	Second-factor login code. Required when the account has email/SMS code login (login_verify) enabled; obtain it first via POST /verify-codes (purpose=login)

Log out

POST/api/v2/auth/logout

Authentication: User

Change password

PUT/api/v2/auth/password

Authentication: User

Request body application/json

Field	Type	Required	Description
new_password	string	Required	New password, 8 to 128 characters
old_password	string	Required	Current password

Reset password

POST/api/v2/auth/password-reset

Authentication: No auth

Request body application/json

Field	Type	Required	Description
channel	string	Required	Recover by email or by phone number Values `["email","sms"]`
code	string	Required	Verification code sent to target (POST /verify-codes, purpose=reset_password)
new_password	string	Required	New password, 8 to 128 characters
target	string	Required	Email or phone number bound to the account

Refresh token

POST/api/v2/auth/refresh

Authentication: No auth

Request body application/json

Field	Type	Required	Description
refresh_token	string	Required	Refresh token, exchanged for a new token pair

Admin SSO login

POST/api/v2/auth/sso

Authentication: No auth

Request body application/json

Field	Type	Required	Description
sso_ticket	string	Required	Login ticket issued by the super admin: base64url (no padding) bytes of a licwire envelope (kind sso_ticket)

Switch admin to user

POST/api/v2/auth/switch

Authentication: Admin only

Request body application/json

Field	Type	Required	Description
user_id	integer	Required	User ID

Log in with a switch ticket

POST/api/v2/auth/switch-login

Authentication: No auth

Request body application/json

Field	Type	Required	Description
switch_ticket	string	Required	One-time switch ticket obtained by an administrator.

Create a one-time switch ticket

POST/api/v2/auth/switch-ticket

Authentication: Admin only

Request body application/json

Field	Type	Required	Description
user_id	integer	Required	User ID

Generate TOTP secret

POST/api/v2/auth/totp

Authentication: User

Enable TOTP

PUT/api/v2/auth/totp

Authentication: User

Request body application/json

Field	Type	Required	Description
code	string	Required	Verification code sent to target (POST /verify-codes, purpose=reset_password)

Disable TOTP

DELETE/api/v2/auth/totp

Authentication: User

Request body application/json

Field	Type	Required	Description
code	string	Required	Verification code sent to target (POST /verify-codes, purpose=reset_password)

Authentication object

Field	Type	Required	Description
access_token	string	—	Access token, sent as Authorization: Bearer
captcha_code	string	—	Characters shown in the captcha image
captcha_id	string	—	Captcha id from GET /auth/captcha; required after repeated failed logins
channel	string	Required	Recover by email or by phone number Values `["email","sms"]`
code	string	Required	Verification code sent to target (POST /verify-codes, purpose=reset_password)
expires_in	integer	—	Access token lifetime in seconds
id	string	—	Pass back as captcha_id when logging in; single use, invalidated after one check whether right or wrong
image	string	—	PNG data URI
key	string	—	Base32 secret (returned only once, here)
must_change_password	boolean	—	Login response only; true means the account still uses the installer-generated initial password and must change it first.
new_password	string	Required	New password, 8 to 128 characters
old_password	string	Required	Current password
otpauth_uri	string	—	otpauth:// URI to add to an authenticator app by scanning
password	string	Required	Login password
recovery_codes	string[]	—	Eight one-time recovery codes (XXXXX-XXXXX), returned only once, when TOTP is enabled
refresh_token	string	—	Refresh token, exchanged for a new token pair
sso_ticket	string	Required	Login ticket issued by the super admin: base64url (no padding) bytes of a licwire envelope (kind sso_ticket)
switch_ticket	string	Required	One-time switch ticket obtained by an administrator.
target	string	Required	Email or phone number bound to the account
token_type	string	—	Token type, always Bearer
totp_code	string	—	Current 6-digit TOTP code, or an unused recovery code (XXXXX-XXXXX, consumed on use); required when the account has TOTP enabled
user_id	integer	Required	User ID
username	string	Required	Username
verify_code	string	—	Second-factor login code. Required when the account has email/SMS code login (login_verify) enabled; obtain it first via POST /verify-codes (purpose=login)

curl

# Get captcha
curl "https://panel.example.com/api/v2/auth/captcha"

# Log in
curl -X POST "https://panel.example.com/api/v2/auth/login"

# Log out
curl -X POST "https://panel.example.com/api/v2/auth/logout" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Change password
curl -X PUT "https://panel.example.com/api/v2/auth/password" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Reset password
curl -X POST "https://panel.example.com/api/v2/auth/password-reset" \
  -H "Content-Type: application/json" \
  -d '{"channel":"email","code":"123456","new_password":"${NEW_PASSWORD}","target":"user@example.com"}'

# Refresh token
curl -X POST "https://panel.example.com/api/v2/auth/refresh"

# Admin SSO login
curl -X POST "https://panel.example.com/api/v2/auth/sso" \
  -H "Content-Type: application/json" \
  -d '{"sso_ticket":"eyJib2R5Ijp7fX0"}'

# Switch admin to user
curl -X POST "https://panel.example.com/api/v2/auth/switch" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":2}'

# Log in with a switch ticket
curl -X POST "https://panel.example.com/api/v2/auth/switch-login"

# Create a one-time switch ticket
curl -X POST "https://panel.example.com/api/v2/auth/switch-ticket" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":2}'

# Generate TOTP secret
curl -X POST "https://panel.example.com/api/v2/auth/totp" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Enable TOTP
curl -X PUT "https://panel.example.com/api/v2/auth/totp" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Disable TOTP
curl -X DELETE "https://panel.example.com/api/v2/auth/totp" \
  -H "X-API-Key: $GOCDN_API_KEY"