Authentication

Authenticate API keys, bound devices, and employee sessions.

API key and device id

Every API-key route requires both headers:

Authorization: Bearer YOUR_API_KEY
X-Device-ID: YOUR_DEVICE_ID

Create a location in the dashboard, then generate its key in access management. Store the secret securely.

Choose a stable identifier for the POS device. The first authenticated request binds the key to X-Device-ID. Reuse that identifier on every request, including login and reads. Missing device ids return 401; using a bound key from another device returns 403. Provision separate keys for separate devices. Regenerating a key clears its device binding.

Revoked or expired keys return 401. Keys tied to archived locations return 403.

Employee sessions

Call employee login with the key, device id, username, and password. Save token and sessionExpiresAt.

X-Employee-Token: YOUR_EMPLOYEE_TOKEN

Send this token on card operations, the employee-protected reward catalog, and logout. Sessions currently last 24 hours. Logout invalidates the supplied session. Log in again when employee authentication returns 401.

Non-admin employees need the API key’s location in locationIds. Empty assignments grant no location access. Admin employees bypass the location assignment check. A location restriction returns 403.

Validate employee credentials accepts a username and password. It does not check an existing token or create a new session.

Authentication by route

Route	API key and device id	Employee token
Card lookup, templates, prices, location, customers, client config, GET /rewards	Required	No
Coupon, loyalty, status, points, redeem, apply, digital create	Required	Required
POST /points-card-rewards, employee logout	Required	Required
Employee login and credential validation	Required	No
GET /payment-sessions/{token}/info	Required	No
Payment-session creation and status	No	No
Public card and card-reward views	No	No

Public payment sessions use the unguessable token as their secret. Keep it private and avoid logging it.