Keys and authentication
Every request carries one key. Which key depends on who is acting: your company as a whole, one particular shop, or your sandbox.
Three kinds of key
| Key | Looks like | Identifies | Works on |
|---|---|---|---|
| Partner key | npv_live_… | Your company, the POS vendor | /pos-partner/v1: link codes, the sandbox, your shops' health and sales |
| Shop key | npk_live_… | One shop (one branch) | /pos/v1: that shop's products, stock and orders |
| Sandbox key | npk_test_… | Your hidden test shop | /pos/v1, plus the sandbox tools that simulate orders |
A business with two branches is two shops, so it has two shop keys. A partner key used on a shop endpoint (or the reverse) is answered with 401 invalid_key.
Getting a partner key
You create it yourself in the developer console, one per POS company.
- Create a developer accountSign up with your company name, work email and mobile number. We text a code to confirm the phone.
- Create your key and sandboxIn the console, open API keys. Each key is shown once and we store only a fingerprint, so copy it somewhere safe straight away.
- Build while we review youWe approve new companies, usually within one working day, and text you when it's done. Until then your partner key works for
POST /pos-partner/v1/sandboxonly; everything else answers403 vendor_pending.
Getting a shop key
A shop key belongs to the shop, so the shop owner always takes part. There are two ways to get one.
With a link code (recommended)
Your POS asks for a short code with its partner key and shows it on the till. The owner types it into the Nunua Pro Business app, and your POS collects the shop key over the API. Nobody copies a key by hand. The steps are in linking a shop.
From the owner
The owner can also connect a POS directly in the Business app (Products menu → POS & CSV import → Connect a POS). The app shows the shop key once, and the owner enters it in your POS settings. This works without a partner key, but the shop then won't appear in your partner dashboard calls, so prefer link codes.
Your sandbox key
POST /pos-partner/v1/sandbox creates your test shop and returns its npk_test_… key once. Call it again with {"rotate": true} if you lose it.
Sending a key
Send the key as a bearer token on every request. There are no sessions, cookies or tokens to refresh.
curl https://nunuapro.app/api/pos/v1/ping \
-H "Authorization: Bearer $NUNUA_KEY"GET /pos/v1/ping is the quickest way to check a shop key: it answers with the shop the key belongs to.
Rotating and revoking
| Who | Can | Then your POS gets |
|---|---|---|
| Shop owner | Rotate the shop key in the Business app | 401 invalid_key on the old key. Link again, or enter the new key. |
| Shop owner | Pause the link | 403 connection_paused. Keep the key; the feed catches up when they resume. |
| Shop owner | Disconnect the POS | 401 invalid_key. The shop must link again. |
| You | Replace the partner key in the console | 401 invalid_key on the old partner key straight away. Shop keys keep working. |
| Nunua Pro | Suspend a partner account | 403 vendor_suspended on partner calls. |
Keeping keys safe
- A shop key can change a shop's prices and stock. Store it like a password: encrypted at rest, never in logs, never in a URL.
- Keep the partner key on your servers only. Never ship it inside the software you install on a shop's computer; a locally installed POS needs only its own shop key.
- Use shop and customer data only to serve that shop, and delete customer data within 30 days of a shop disconnecting. These rules are part of the Developer Terms.
- If a key may have leaked, rotate it at once: the owner rotates a shop key in the app, and you replace the partner key in the console (API keys → Replace this key).
The developer console also shows each linked shop's sync health and every failed call made with your keys over the last 14 days. The same health data is available over the API, from GET /pos-partner/v1/shops and GET /pos-partner/v1/stats.