☰ Menu · Keys and scopes
Keys and scopes
Every request carries a secret key in the Authorization header. A key belongs to one venue and can be limited to what the integration needs.
curl https://loyaltyfy.io/api/v1/account \
-H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"Send the key as Authorization: Bearer <key>. Requests without a key, with an unknown key or with a revoked key get 401.
Test and live keys
Keys start with sk_test_ or sk_live_. Both work against the same venue and the same data; the difference is the livemode flag on everything a key creates, so reports and webhooks can tell test traffic apart. Use test keys while you build, switch to a live key on the first real shift.
Scopes
A key can be limited to some scopes. A call that needs a scope the key does not have gets 403 with code missing_scope. A key created with no scopes has full access; we only recommend that for the venue's own scripts.
| Scope | Allows |
|---|---|
| members:read | Look up members, list them, read history, scan codes. |
| members:write | Enrol members, update profiles, attach card numbers. |
| members:adjust | Add or take cashback by hand with a reason, when the venue allows it. |
| transactions:write | Apply and void checks, record visits, redeem rewards, list transactions. |
| menu:read | Read the menu and dishes. |
| menu:write | Create dishes, change prices, manage the stop list. |
| orders:read | Read table orders. |
| orders:write | Accept, reject and move orders through statuses. |
| devices:write | The kiosk and scanner bundle: scans, visits, enrolment and reward redemption, without access to the member list or checks. |
| catalog:read | Read products and category rules. |
| catalog:write | Upload products and name categories. Category money rules stay with the owner. |
| webhooks:write | Manage webhook endpoints. |
Typical sets: a till needs members:read, members:write, transactions:write. A door scanner needs only devices:write. A menu sync needs menu:read and menu:write; add orders:read and orders:write if the POS takes table orders.
Keeping keys safe
- Keys are secret. Call the API from your server or from the till's back office, never from a browser or a public mobile app.
- We store only a hash of each key. If a key is lost, revoke it in the dashboard and create a new one; it takes effect immediately.
- Use one key per installation (per till, per kiosk) when you can. Revoking one then does not stop the others, and Last used in the dashboard tells you which device is talking.