Authentication
API keys, scopes, expiry and revocation.
Every request is authenticated with a store API key, sent as a bearer token:
GET /v1/store HTTP/1.1
Host: api.zaher.io
Authorization: Bearer zk_live_4f7Qm9...A key belongs to one store. It looks like zk_live_ followed by 32
characters, and it's shown once, when you create it — Zaher stores only a
hash. If you lose a key, revoke it and create a new one.
Creating keys
Keys are managed in Settings → APIs & Webhooks → API keys. When you create one you choose:
- A name, so you know later what uses it.
- Access — Read only, Full access, or Custom per resource. You can only grant access you have yourself in the dashboard.
- Expiry — never, 30 days, 90 days or 1 year.
Create API key
Name
Then copy the key. It's shown this one time only:
Copy your API key now
This is the only time the full key is shown. Store it somewhere safe.
zk_live_4f7Qm9xKp2LwR8vT1nYc6bHs3dJe0aGu CopyThe store owner gets an email whenever a key is created or revoked.
Scopes
Each key carries scopes. A :write scope includes the matching :read.
| Resource | Scope | Allows |
|---|---|---|
| Orders | orders:read | GET /orders · GET /orders/{id} |
orders:write | POST /orders/{id}/fulfillment, plus everything read allows | |
| Bookings | bookings:read | GET /bookings · GET /bookings/{id} |
bookings:write | POST /bookings/{id}/accept · POST /bookings/{id}/cancel, plus everything read allows | |
| Products & stock | products:read | GET /products · GET /products/{id} |
products:write | PATCH /products/{id}/variants/{variant_id} · POST /products/{id}/variants/{variant_id}/stock, plus everything read allows | |
| Customers | customers:read | GET /customers · GET /customers/{id} |
customers:write | Reserved for upcoming write endpoints, plus everything read allows |
GET /store needs no scope — any valid key can call it, which makes it a
handy way to check a key and see its scopes.
Plans and limits
API access is part of the Pro plan and above.
| Plan | Requests per minute | API keys |
|---|---|---|
| Pro | 60 | 5 |
| Advanced | 300 | 20 |
If a store moves below Pro, its keys stop working with
403 plan_required — they aren't deleted and work again after upgrading.
Rotating and revoking
There's no in-place rotation: create a new key, switch your system to it, then revoke the old one. Revoking takes effect immediately.
Authentication errors
| Status | code | Meaning |
|---|---|---|
| 401 | missing_api_key | No Authorization: Bearer … header |
| 401 | invalid_api_key | Not a key, or not one we know |
| 401 | revoked_api_key | The key was revoked |
| 401 | expired_api_key | The key passed its expiry date |
| 403 | insufficient_scope | The key lacks the scope this endpoint needs |
| 403 | plan_required | The store's plan doesn't include the API |
Keep keys on your server
Store keys in environment variables or a secrets manager. Never put one in front-end code, a mobile app or a public repository. If a key leaks, revoke it right away.