Authentication and User Management

FastBee uses local accounts to protect web pages and device APIs. After a successful login, the device maintains the session via an HttpOnly cookie; scripts can also declare an API client in the login request and read the returned session ID.

Basic Operations

1. Enter the username and password on the device login page.
2. Change the default administrator password immediately after first deployment.
3. Automation scripts should reuse the Cookie from the login response and must not create large numbers of sessions concurrently.
4. When pages keep returning 401, log in again; do not misread auth expiry as a network or memory fault.

Login, logout, and changing one's own password are core authentication capabilities. User list, add-user, and account unlock belong to the optional userAdmin feature; when it is not compiled or not enabled, the corresponding menus and APIs are unavailable.

Passwords and Sessions

• New passwords are stored with PBKDF2-HMAC-SHA256, by default 20,000 iterations, a 16-byte random salt, and a 32-byte derived key.
• Legacy-format passwords are automatically migrated to PBKDF2 format after a successful verification.
• The default password length is 6-32 characters; production deployments should use longer, non-reused passwords.
• By default, 5 consecutive login failures lock the account for about 5 minutes; it can also be unlocked by a logged-in user via the user-management page.
• The default session timeout is 1 hour, and only a limited number of active sessions are kept.
• By default sessions are memory-only; a restart requires logging in again.

The security policy is stored in /config/auth.json, and user records in /config/users.json. The current firmware has no separate authentication-policy REST configuration routes; do not call endpoints that do not exist per old documentation.

Authentication API

Method	Path	Description
POST	/api/auth/login	Log in and set the session cookie
GET	/api/auth/session	Query the current session; returns sessionValid: false when not logged in
POST	/api/auth/logout	Log out the current session and clear the cookie
POST	/api/auth/change-password	Change the current user's password; existing sessions of that user become invalid on success

The login and change-password endpoints use form parameters:

$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession

Invoke-WebRequest -Uri "http://<device-sta-ip>/api/auth/login" `
  -Method POST -WebSession $session `
  -Body @{ username = "admin"; password = "<current-password>" }

Invoke-WebRequest -Uri "http://<device-sta-ip>/api/auth/change-password" `
  -Method POST -WebSession $session `
  -Body @{ oldPassword = "<current-password>"; newPassword = "<new-password>" }

Password verification runs in a separate task to avoid blocking the network thread. When device resources are insufficient or too many logins happen at once, 503 with Retry-After may be returned; clients should wait and retry serially.

User Management API

The endpoints below require a valid session and userAdmin to be active:

Method	Path	Description
GET	/api/users?page=1&limit=20	Query users paged
GET	/api/users/{username}	Query a single user
POST	/api/users	Add a user; parameters are username, password, optional description
POST	/api/users/update	Update password, enabled state, or description
DELETE	/api/users/{username}	Delete a user; the currently logged-in account cannot be deleted
GET	/api/users/online	Query active sessions
POST	/api/users/reset-password	Reset the specified user's password and invalidate their sessions
POST	/api/users/unlock-account	Clear the login-failure lock of the specified user

The current user model provides no admin/operator role fields. All user-management endpoints use "authenticated" as the access condition; restrict the reachable range of the device's management network during deployment.

Common Issues

Symptom	Diagnosis and handling
Login returns 401	Verify the username, password, and case; after consecutive failures, wait for the lock to clear
Login returns 503	Device memory or login task slots are busy; retry serially per Retry-After
API returns 401	Session cookie missing or expired; log in again and reuse the new cookie
Logged out immediately after password change	Normal behavior; a password change logs out that user's existing sessions
User-management menu not shown	Check in Feature Config whether userAdmin is compiled and enabled
Password of the only account forgotten	Follow the device recovery flow for factory reset or reflash; the operation wipes the existing config — evaluate the data impact first

Security Recommendations

• Do not store real passwords and session IDs in documentation, public config packages, or Git history.
• Production networks should restrict the reachable range of the device's web management interface.
• The HTTP management page itself is not equivalent to HTTPS; MQTTS only encrypts the MQTT link and provides no TLS for web pages.
• Check sensitive files such as auth.json before exporting configs; public examples keep only placeholder information.

Related Documentation

• Feature Configuration
• API Reference
• Stability and Release Checklist