Authentication

Login

POST /api/login.php
Content-Type: application/json

{
  "username": "user",
  "password": "password"
}

Response (Success, no 2FA)

{
  "success": true,
  "user": {
    "id": 1,
    "username": "user",
    "display_name": "User Name",
    "role": "admin"
  }
}

Response (2FA Required)

{
  "success": true,
  "requires_2fa": true
}

The session is created in 2fa_pending state. Submit the TOTP code:

POST /login-2fa.php
Content-Type: application/json

{
  "totp_code": "123456"
}

Response (Error)

{
  "success": false,
  "error": "Invalid credentials"
}

After 5 failed attempts, the account is locked for 15 minutes.

Session Management

Authentication creates a PHP session. The session cookie (PHPSESSID) must be sent with all subsequent requests.

Session Data

$_SESSION['user_id']     // User ID
$_SESSION['username']    // Username
$_SESSION['role']        // 'admin' or 'user'
$_SESSION['display_name'] // Display name

Bearer Token Authentication

For API access (e.g., from the local client), Bearer tokens are supported:

GET /api/filesystem.php?action=list
Authorization: Bearer <token>

Tokens are issued during the sync authentication flow.

Two-Factor Authentication (2FA)

Niuton supports TOTP-based 2FA (RFC 6238):

Enable 2FA

POST /api/settings.php?action=setup_2fa

Returns a QR code URL and secret key.

Verify & Enable

POST /api/settings.php?action=enable_2fa

{
  "totp_code": "123456"
}

Disable 2FA

POST /api/settings.php?action=disable_2fa

{
  "totp_code": "123456"
}

Backup Codes

When 2FA is enabled, 8 single-use backup codes are generated. Regenerate with:

POST /api/settings.php?action=regenerate_backup_codes

{
  "totp_code": "123456"
}

Maintenance Mode

When maintenance mode is enabled, all sessions are terminated and login is restricted to admin accounts only.