Staff and Roles
Hyvä POS is on the App Store
The free app is out for iPhone, iPad and Mac: install it from the App Store, connect your Magento store and sell. PRO, the Magento module with a license per terminal, follows shortly. News and pricing are at hyva.io/pos.
On the free tier, the register has one user. PRO gives every employee their own PIN, with permissions that come from roles you manage in Magento, so the register records who performed each action and enforces what each person may do.
PIN Login
Staff members are created in the Magento admin (Hyvä POS → Staff → Manage Staff) and assigned to locations and a role. On the register, each shift starts with a PIN: the sale, the drawer opening, the stock change all carry the person who did them, and reports show it. Every staff record also carries a staff ID (an employee code, generated when the record is created): choose it as the receipt's staff-name format and receipts stay anonymous for customers while the store can still trace every sale to a cashier; see receipt layout.
Whether the register requires a login is a Magento switch: Stores → Configuration → Hyvä POS → General → Require Staff Login.
What Magento Stores
A staff record is a name, an email, a staff ID, location assignments, a role, and a PIN. The PIN never exists in readable form on the server: Magento stores only a bcrypt hash, and that hash is never sent to devices: the API that ships staff lists to registers omits it. Each successful online login is recorded as a session in Magento, and every consequential action a staff member takes at the register lands in the audit log (Hyvä POS → Operations → Audit Log) with their name on it.
Roles and the 50 Permissions
Roles are managed under Hyvä POS → Staff → Roles. Every permission is an individual switch on the role, 50 of them, grouped as on the role form:
- Sales (10): place orders, apply discounts, apply coupons, custom line items, issue refunds, approve returns, void orders, price override, tax-exempt sales, reverse charge.
- Payments (5): accept cash, card, split payment, store credit, pay by invoice.
- Register (4): open register, close register, cash in/out, view register history.
- Customers (4): view, create, edit, assign customer group.
- Catalog (6): view products, view stock levels, manage stock, assign location to product, toggle ship-together, edit checkout dashboard.
- Reporting (3): view reports, view daily summary, export reports.
- Staff & Admin (4): view users, manage users, assign roles, view audit log.
- Settings (9): all settings: save, all settings: read, and one switch per part of the device's Settings (license and subscription, barcode scanner, printers, payment terminal, customer display, self-checkout, appearance and display).
- Hardware (3): open cash drawer, print receipts, print barcode labels.
- Held Transactions (2): hold cart, recall any cart.
Three roles ship as defaults:
| Role | In one sentence |
|---|---|
| Cashier | Sells and runs their own register shift. Discounts and price changes take a manager's approval; no returns, refunds, voids, stock changes or settings |
| Manager | Runs the floor: discounts, refunds, cash in/out, stock, customer management, reports |
| Admin | Everything, including staff management, role assignment, settings and report export |
Duplicate and adjust them, or build your own: every permission is set on the role, and the register enforces it per action.
Manager Approvals
Some actions can be approved for one sale instead of granted to a role. When a cashier's role does not allow the action, the register opens the Manager approval sheet: "A staff member whose role allows this approves it with their passcode. You stay signed in." The approver picks their name and enters their PIN on the cashier's device; the cashier stays signed in and the sale continues. When nobody on the device's staff list may approve it, the sheet shows "No staff member on this device may approve this."
| Action | Approved by a role with |
|---|---|
| Line discount, cart discount | Apply Discounts |
| Price change | Price Override |
| Paying out a refund | Issue Refunds |
| Refund difference write-off | Manager or Admin role |
| Resolving a payment the store did not book | Manager or Admin role |
An approval covers one action, on one line or the cart, for one amount. A discount approval is bound to the money it takes off: a cart that grows under a percentage discount needs a new approval, a smaller one keeps it. Each approval is used once. The default Cashier role has neither Apply Discounts nor Price Override, so a cashier's discount or price change always takes an approval; the Manager and Admin roles have both.
Returns use two permissions. Approve Returns opens the return wizard and prepares a return. Issue Refunds pays the money out. A staff member with Approve Returns but not Issue Refunds prepares the return and asks a manager to approve the payout. That approval lists the order, the return, the lines and each part of the refund with its destination and amount, and covers that refund only. With module 1.5.0 the store confirms the approval as well, which needs a connection; see who may refund.
Every approval is recorded on the sale and sent to Magento, which adds a comment to the order's history that the customer does not see, for example "Cart discount approved by Jane Manager for John Cashier, 10.00." The register keeps the approvals on the device until the module accepts them; a module older than 1.5.0 has no route for them, and they wait on the device until the module is updated.
The Security Details
- First login must be online; from then on the PIN verifies offline against a securely cached, salted slow hash (never the PIN itself), compared in constant time.
- PIN changes invalidate the cache everywhere. Each staff record carries a change watermark that is stamped in the same operation that stores the new PIN, so the two cannot drift apart. Registers receive the watermark with every staff sync; a mismatch drops the cached credential immediately and forces one online login with the new PIN. With module 1.5.0 a changed PIN reaches every connected register at its next heartbeat; an earlier module delivers it when the app next starts. A device that is offline when the change happens keeps accepting the old PIN until it reconnects, for at most 24 hours after the store last confirmed it.
- Offline sign-in lasts 24 hours. A cached PIN is valid for 24 hours from the last time the store confirmed it: an online sign-in, a staff sync, or a heartbeat that reports the location's staff unchanged. A register that stays connected renews this by itself. A register that has been offline longer asks for the connection at the next sign-in or unlock: "Connect to the store to verify your sign-in. Your saved verification has expired." The 24 hours are measured on a clock the register checks, so setting the device clock back does not extend them. After the update to app 0.4.0, each staff member signs in once online before offline sign-in works again (see Upgrading).
- Lockouts are graduated and per person: repeated wrong PINs lock that staff member out on a rising schedule (15 seconds after 3 failures, 1 minute after 5, 5 minutes after 8, 30 minutes after 12) without affecting colleagues. The failure counter resets after 24 hours. The lockout is enforced server-side and the app does not fall back to offline verification while locked, so offline mode cannot bypass it. An admin can unlock early from Magento.
- Inactivity locks the register after a configurable timeout (5 minutes by default); unlocking takes the PIN again.
Changes Reach Devices Fast
PIN changes, role changes and deactivations reach the registers through the heartbeat, within minutes, on module 1.5.0; an earlier module delivers them when the app next starts. A role change applies at once to a staff member who is signed in. Deactivating a staff member in Magento, or removing them from the location, is how you off-board: their PIN stops working, and a register where they are signed in locks with "Your staff account is no longer active on this device. Another staff member can sign in." What they already did stays recorded under their name. There is nothing to clean up on the devices themselves; the registers read the staff list from Magento rather than keeping their own copy.
Offline
After the first online login, PIN verification works offline for 24 hours from the store's last confirmation of that PIN, so a network outage does not lock staff out mid-shift. Offline mode cannot bypass a server-side lockout or re-enable a changed PIN: both are checked against Magento when the connection returns, and a changed PIN stops working at the next staff sync.