How to register and pair a POS terminal, waiter tablet, or kitchen display
Why Is Device Pairing Required?
Important Security Note
POX Studio uses a two-layer security model for POS operations:
1. User authentication — staff log in with their email/password or PIN.
2. Device authentication — the physical device (tablet, PC, phone) must be registered by an admin before it can accept logins or process payments.
This means even if someone knows a staff PIN, they cannot process orders unless they are on an approved, registered device. This protects your business from:
• Unauthorized access from unknown devices
- Staff processing orders outside your premises
- Cashier fraud or PIN sharing across untrusted hardware
Device pairing is a one-time setup per device. Once paired, the device remains trusted until you revoke it from the Devices page.
Device Types
POS / Cashier
The main sales terminal. Used to take orders, apply discounts, and process payments. Typically a tablet or PC at the counter.
Waiter Tablet
A handheld device used by waitstaff to take tableside orders. Orders go directly to the kitchen display.
Kitchen Display (KDS)
A screen mounted in the kitchen that shows incoming orders in real time. Kitchen staff mark tickets as done from this screen.
Step 1 (Admin): Create the Device from the Dashboard
The Owner or Admin must perform these steps from the web dashboard before touching the physical device.
Go to Devices
From the left sidebar, go to Settings → Devices. You will see four status counters at the top (Total, Active, Pending, Revoked) and a list of all your registered devices. On a fresh account this list will be empty.
Devices page showing Total, Active, Pending, Revoked counters and empty device list
Click '+ Add Device'
Click the '+ Add Device' button in the top-right corner. A modal will appear with three fields to fill in.
Give it a clear physical name so you can identify it later. Examples: Counter 1, Kitchen Screen, Table Tablet.
Counter 1 · Kitchen Screen · Table Tablet · Waiter A
Select what this device will be used for. POS/Cashier for the main counter, Waiter Tablet for tableside ordering, Kitchen Display for the KDS screen.
Select which branch this device belongs to. If you only have one location it will be pre-selected. You must create a location first if the list is empty.
Add New Device modal with Device Name, Device Type selector, and Location dropdown
Click 'Generate Pairing Code'
After filling in all three fields, click the '+ Generate Pairing Code' button. POX Studio will create the device record and generate a unique set of credentials.
Save the Pairing Credentials
A credentials modal will appear showing two items you must copy to the device:
• Pairing Code — a 6-digit number (e.g. 483920)
• Pairing Secret — a long hex string (64 characters)
You can click the copy icon next to each value. The eye icon reveals the secret.
The pairing credentials expire in ~10 minutes. If they expire before you use them, close this modal and click the three-dot menu (⋮) on the device row → 'New Pairing Code' to regenerate.
Pairing credentials modal showing the 6-digit pairing code and the masked pairing secret with copy buttons
Step 2A (Web Browser): Pair the POS Terminal
If you are using POX Studio on a web browser (PC or tablet browser), follow these steps on the device you want to use as the POS terminal.
Open the POS Terminal Page
On the device you want to pair, open a browser and log in to POX Studio. Then navigate to Dashboard → POS Terminal. If the device has not been paired yet, you will see the 'Pair this terminal' screen automatically.
Enter the Pairing Code
On the 'Pair this terminal' screen, enter the 6-digit Pairing Code in the first field.
'Pair this terminal' screen with Pairing Code and Pairing Secret fields
Enter the Pairing Secret
Paste the long pairing secret (64-character hex string) in the second field. This is the value from the credentials modal you copied in admin Step 4.
Click 'Pair terminal'
Click the 'Pair terminal' button. If successful, the device token is saved to this browser and you are redirected to the POS terminal immediately. The device status in Dashboard → Devices will change from 'Pending' to 'Active'.
The device token is tied to this browser on this machine. If you open a different browser or clear browser data, you will need to re-pair.
Step 2B (Mobile App): Pair the Mobile Device
If you are using the POX Studio mobile app (Android or iOS), follow these steps on the phone or tablet.
Open the App
Open the POX Studio app on the mobile device. Log in with your email and password (or PIN if already set up). After login, the app checks automatically whether this device has been paired.
The 'Pair this device' Screen Appears
If the device has not been paired, the app will automatically show the 'Pair this device' screen. You will see:
• A 'How to get your pairing code' instruction card explaining the 4-step process.
• Two input fields: Pairing Code and Pairing Secret.
• A 'Previously paired device' card if this device was paired before (shows type, location, and date).
Enter the 6-Digit Pairing Code
Tap the first field and type the 6-digit code from the admin credentials screen. The keyboard will automatically switch to numeric.
Enter the Pairing Secret
Tap the second field and paste (or type) the 64-character pairing secret. Tip: copy it from the admin dashboard first, then paste it here to avoid errors.
Tap 'Pair Device'
Tap the 'Pair Device' button. The app contacts the server to verify the credentials. If successful, you will see a green 'Device paired! Redirecting…' banner and the app will take you directly to the POS, KDS, or waiter screen depending on the device type you selected.
Re-pair from Mobile Settings
If a device needs to be re-paired later (e.g. token expired or device was revoked and re-added), go to the app's More tab → Settings → and look for the 'Pair Device' option. The admin must generate a new pairing code first.
What Happens After Pairing?
- The device status in Dashboard → Devices changes from 'Pending' to 'Active'.
- Staff can now log in to the POS terminal using their 4-digit PIN instead of their full email and password.
- The device sends a unique X-Device-Token header with every API request, allowing the server to enforce per-device permissions.
- On mobile, the device info (type, location, paired date) is cached locally so it remains visible even when the app is offline.
- The POS terminal, waiter tablet, or KDS screen is now fully operational.
Managing Devices After Pairing
Re-pair a Device
If a device token expires, you are changing the physical device, or a browser's data was cleared — click the ⋮ menu on the device row and select 'Re-Pair Device'. A new pairing code and secret will be generated. Enter these on the device.
Revoke a Device
If a device is lost, stolen, or no longer in use — click ⋮ → 'Revoke Access'. The device immediately loses all access. The device entry remains in your list with 'Revoked' status for your records.
Rename a Device
Click ⋮ → 'Rename' to change the display name. Useful when you physically move a device to a different counter or role.
Troubleshooting
Pairing code is expired
Go to Dashboard → Devices, click ⋮ on the device row, and select 'New Pairing Code'. A fresh code valid for ~10 minutes will be generated.
DEVICE_TOKEN_INVALID error on POS
The device token stored in this browser or app has expired or was revoked. Go to Dashboard → Devices → ⋮ → Re-Pair Device, then enter the new credentials on the device.
Location list is empty in Add Device modal
You must create at least one location before adding devices. Go to Settings → Locations → Add Location first.
Pairing fails with 'Pairing code must be a 6-digit number'
Make sure you are entering only the numeric 6-digit code, with no spaces or letters. Do not confuse it with the secret.
Staff PIN login not working after pairing
PIN login is only available after a device is fully paired (status = Active). Also ensure staff members have a PIN set in Dashboard → Staff → the staff member's profile.