Skip to content

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.