Authentication & Session API

WisPanel uses JWT Bearer tokens for authentication. Tokens are obtained via login and included in all subsequent requests.

Base URL

https://YOUR_SERVER:3082/api/v1

Login

POST /api/v1/auth/login

Rate limited: 20 requests/minute per IP.

Request Body

{
  "username": "admin",
  "password": "your_password",
  "totp_code": "123456",
  "force": false
}

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "username": "admin",
    "email": "[email protected]",
    "role": "admin",
    "status": "active",
    "max_domains": -1,
    "max_databases": -1,
    "can_use_ssl": true,
    "can_use_ssh": true,
    "can_use_cron": true
  },
  "expires_in": 86400
}

Response 200 (2FA Required)

{
  "requires_2fa": true,
  "message": "Two-factor authentication required"
}

Response 409 (Single Session Conflict)

{
  "existing_session": true,
  "session_info": {
    "ip": "192.168.1.10",
    "device": "Chrome on Windows",
    "login_at": 1714123456,
    "last_seen": 1714127000
  },
  "message": "Active session detected on another device"
}

Using the Token

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Or via query param (SSE only): ?token=YOUR_JWT_TOKEN

Logout

POST /api/v1/auth/logout

Returns {"message": "Logged out successfully"}

Get Current User

GET /api/v1/auth/me

Returns the authenticated user object (same as login response user field).

Refresh Token

POST /api/v1/auth/refresh

Tokens auto-refresh (sliding window) when less than 50% lifetime remains. The new token is returned in the X-New-Token response header.

Re-authenticate (Sensitive Operations)

Some endpoints require re-authentication (within last 5 minutes).

POST /api/v1/auth/reauth

{ "password": "your_password" }

Login As User (Reseller/Admin)

POST /api/v1/auth/login-as/{username}

Requires reseller or admin role. Returns a new token scoped to the target user.

Return to Admin

POST /api/v1/auth/return-to-admin

Restores original admin/reseller session after login-as.

Two-Factor Authentication

Get 2FA Status

GET /api/v1/auth/2fa/status

Setup 2FA

POST /api/v1/auth/2fa/setup

Requires reauth. Returns QR code URI and backup codes.

Verify 2FA Setup

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

{ "code": "123456" }

Disable 2FA

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

Requires reauth.

Change Password

POST /api/v1/auth/change-password

Requires reauth.

{
  "old_password": "current_pass",
  "new_password": "new_secure_pass"
}

API Keys (per user)

GET    /api/v1/users/{username}/api-keys
POST   /api/v1/users/{username}/api-keys          # Requires reauth
GET    /api/v1/users/{username}/api-keys/{key_id}
PUT    /api/v1/users/{username}/api-keys/{key_id}
DELETE /api/v1/users/{username}/api-keys/{key_id} # Requires reauth
POST   /api/v1/users/{username}/api-keys/{key_id}/toggle

Error Responses