Authentication
Every request carries a secret key in the Authorization header:
Authorization: Bearer nz_live_sk_...
Keys
- Who makes them: a store's owners and admins, in Settings → Developers.
- What a key belongs to: one store, not a person. It keeps working when the person who made it leaves.
- Shown once: only a fingerprint is kept. If a key is lost, roll it to get a new one.
- Easy to spot: keys start with
nz_live_sk_and end with a checksum, so secret scanners can recognise a leaked key. - Server only: a request carrying a key from a browser (one with an
Originheader) is refused withbrowser_request_refused. Never put a key in a website, a mobile app or a public repository.
Rolling and revoking
- Roll a key to replace it. You get a new key with the same permissions, and the old one keeps working for 24 hours, so you can switch over without downtime.
- Revoke a key to stop it at once, for example if it was leaked.
A revoked, expired or unknown key, or a key of a suspended account, gets 401 invalid_api_key. The answer is the same in every case, on purpose.
Permissions (scopes)
Choose only what the system needs. Changing something includes seeing it.
| Scope | Allows |
|---|---|
read_products |
See products and variants |
write_products |
Create and change products and variants |
read_inventory |
See stock levels |
write_inventory |
Adjust and set stock |
read_orders |
See orders, including shoppers' names and addresses |
write_orders |
Cancel orders |
read_customers |
See customers' names, emails and phone numbers |
read_costs |
See product costs; also needed to set a cost |
A request needing a scope the key lacks gets 403 insufficient_scope, and the message names the scope. Permissions can be changed in Settings → Developers at any time, without a new key.
GET /v1/store needs no scope: use it to check a key works.
Shoppers' data
Orders and customers carry personal details. How many orders and customers each key reads per day is shown to the store's owners and admins on Settings → Data exports. Read only what you need, and keep it as safe as the store would.