Cashier Login
The Cashier Login screen appears after the required HandyCafe account activation step on a configured server. Every Admin or Cashier must authenticate before accessing the dashboard. This page explains the login process, security protections, and what to do if your account is locked.
Login Screen
The login screen appears as a centered card on a clean background with a subtle teal radial glow. It contains:
- HandyCafe logo. Displayed at the top of the card for brand identification.
- Application name. "HandyCafe Server" is shown below the logo.
- Sign-in heading. The Sign In title with the subtitle Sign in to continue.
- Username field. A text input with an account icon on the left side.
- Password field. A password input (masked characters) with a lock icon on the left side.
- Sign In button. A teal button that submits the credentials.
- Card prompt. Or tap your NFC card appears under the button when staff card sign-in is turned on. See Signing In with a Card.
- Forgot admin password? link. Opens the Reset admin password dialog, which resets the Admin password through your HandyCafe account.
- Version number. The current application version is displayed at the bottom of the card.
Logging In
To log in to HandyCafe Server:
- Enter your username. Click the username field (it is focused automatically when the screen loads) and type your username.
- Press Tab or click the password field. Move to the password field.
- Enter your password. Type your password.
- Press Enter or click Sign In. Submit your credentials.
Keyboard Navigation
The login form supports full keyboard navigation:
- Tab moves focus from the username field to the password field.
- Enter in the username field moves focus to the password field.
- Enter in the password field submits the form.
Visual Feedback During Login
When the Sign In button is clicked:
- The form fields reduce to 60% opacity, indicating that a login attempt is in progress.
- The Sign In button changes to a gray disabled state and cannot be clicked again until the attempt completes.
- The cursor changes to indicate that interaction is blocked during processing.
Signing In with a Card
When staff card sign-in is turned on, a cashier or admin can tap their own NFC card on the reader instead of typing a password. The login screen shows Or tap your NFC card while it listens for the reader.
- Turn it on in Settings > Staff > Cashiers with Allow staff to sign in to the server with a card.
- Give each person their own card with the card button on their row.
- A member's card never opens the server. A deactivated cashier's card is refused.
- After 10 failed taps within 10 minutes, card sign-in is locked for 15 minutes. Password sign-in keeps working.
See Member Cards for card stock, lost cards and logging.
Successful Login
After a successful login:
- The current cashier is loaded into the application state.
- The cashier's role and permissions are retrieved from the server.
- The login screen is replaced by the main dashboard. It opens on the first sidebar page the cashier can access, usually Monitoring.
- Sidebar navigation items are filtered based on the cashier's role permissions. Pages the cashier does not have access to are hidden.
Error Handling
If a sign-in fails, an error notification appears for a few seconds with the reason. The messages on the server login screen are:
| Message | Cause |
|---|---|
| Username and password cannot be empty. | One or both fields were left blank. This appears as a warning and nothing is sent to the server |
| Incorrect username or password. | The username or password is wrong, or the cashier account is deactivated or deleted |
| Too many failed login attempts. Please wait 15 minutes and try again. | The username is locked after repeated failures. See Server Sign-In Lockout |
Card sign-in has its own messages:
| Message | Cause |
|---|---|
| Card sign-in for staff is off. Turn it on under Settings, Staff. | Staff card sign-in is turned off |
| This card does not open the operator screen. | The card is not a staff card, for example a member card |
| This card has not been given to anyone yet. | The card is in stock but not assigned |
| This card was cancelled. | The card has been revoked |
| The reader sent an unreadable card number. | The reader sent an invalid card number |
| The card could not be checked. Try again. | A temporary database error. It does not count as a failed attempt |
| Too many cards were refused. Card sign-in is paused for a while. Sign in with a username and password. | Card sign-in is locked after repeated refused cards |
After a failed password sign-in, the password field is cleared and focus returns to the username field so the cashier can try again. When the fields were empty, the password is kept and focus moves to the username field.
Error messages are translated into the currently selected language. If no translation exists for a specific error code, the raw error code is displayed.
Server Sign-In Lockout
The server's own login screen limits password guessing per username. After 5 failed attempts for the same username within 10 minutes, that username is locked for 15 minutes. The screen then reports Too many failed login attempts. Please wait 15 minutes and try again. A successful sign-in clears the counter.
Brute-Force Protection on Client PCs
Sign-ins on client PCs have their own brute-force protection. It operates at two levels:
Device-Level Lockout
Failed login attempts are tracked per client device (identified by MAC address):
- After more than 5 failed attempts from the same device, the device is locked for 3 minutes (180 seconds).
- During the lockout period, all login attempts from that device are rejected with a "device locked" error, even if the correct credentials are provided.
- The lockout timer is displayed to the user so they know when they can try again.
- After the lockout expires, the attempt counter continues from where it left off. The next failure triggers another lockout.
Username-Level Protection
Failed login attempts are also tracked per username:
- After 3 failed attempts for a username that belongs to a cashier, that cashier account is automatically deactivated. This protects privileged accounts from being brute-forced through client PCs.
- A deactivated cashier account cannot log in until an administrator reactivates it.
- Member accounts are never deactivated automatically. Members are protected by the device-level lockout above; failed attempts on a member username do not disable the account.
Security Alerts
When a device lockout is triggered, the server emits a security alert event to the dashboard. This causes:
- A notification to appear in the server UI alerting the on-duty cashier.
- An audible beep sound to draw attention.
- The alert includes the device hostname, the username that was attempted, and the lockout duration.
Audit Logging
Every failed login attempt is recorded in the system logs with:
- The category "auth" and action "loginRejected"
- The hostname and IP address of the client device
- The attempted username and the reason for rejection
This creates a complete audit trail that administrators can review from the Logs page.
Clearing a Lockout
If a legitimate user is locked out, an administrator or authorized cashier can clear the lockout from the Computers page:
- Find the locked client PC on the Computers page.
- Choose Unlock Login in the computer's menu or in the command bar. This resets the device's failed attempt counter and clears the lockout timer.
The device and username failure counters are also automatically cleared on a successful login.
Admin vs. Cashier Accounts
There are two types of accounts that can log in to HandyCafe Server:
Admin Account
- Created during the First Setup Wizard when HandyCafe Server is installed for the first time.
- Has unrestricted access to all pages and features.
- Can create, modify, and delete other cashier accounts.
- Can configure system settings, pricing, and all other administrative functions.
Cashier Accounts
- Created by an administrator in Settings > Staff > Cashiers. See Staff Settings.
- Assigned a role that defines which pages they can access and which actions they can perform.
- Cannot access pages or features that their role does not permit.
- See Cashier Roles and Permissions for details on configuring roles.
Troubleshooting
"I forgot my password"
Cashiers must contact an administrator to reset their password. If the Admin password is lost:
- Select Forgot admin password? on the staff login screen.
- In Reset admin password, choose the account under Admin account.
- Select Reset with handycafe.com account. The server shows Waiting for approval and opens the handycafe.com page in your browser.
- Sign in there with the HandyCafe account that owns this cafe's license and set the new password.
- The server applies the new password by itself. Sign in with it.
This option requires an active internet connection. After 5 failed attempts the form is locked for 15 minutes. See HandyCafe Account.
"My account is deactivated"
A cashier account may have been deactivated by the brute-force protection system (3 failed username attempts) or manually by an administrator. Member accounts are only deactivated manually. The server login screen reports a deactivated account as Incorrect username or password. Ask your administrator to reactivate the account.
"The login screen does not appear"
The staff login screen appears only after release account activation succeeds. A first-time installation shows the First Setup Wizard after account activation when no local Admin exists.
Next Steps
- Dashboard: Understand the main interface after logging in
- Cashier Roles and Permissions: Learn about role-based access control
- First Setup Wizard: How the initial admin account is created