Authentication
API keys, scopes, and the plain refusals.
API keys
Every request carries a platform API key in its Authorization header:
Authorization: Bearer kp_ab12cd34ef56_...
You make keys in your dashboard, once Kiuki has approved your organisation: live keys and sandbox keys, each with the scopes you choose. A key is shown once, when you make it: Kiuki keeps only a fingerprint, so copy it into your system's secret store then. Its first part (kp_ab12cd34ef56) stays visible in the dashboard, so you can tell your keys apart.
Keep keys on your servers. Never put one in a web page, a mobile app or anything a shopper can read. If one leaks, revoke it in the dashboard: it stops working at once.
Everyone your organisation's owners invite on its Team page signs in to the dashboard with their own email address and can make and revoke keys: developers, and owners, who also run the team.
Scopes
A key can do only what its scopes allow. Give each program the scopes it needs and no more.
| Scope | Lets the key | Endpoints |
|---|---|---|
catalogue:read | Read live listings in a market: packs, labels, prices and availability. | GET /v1/catalogue, GET /v1/catalogue/{listing_id} |
quote:write | Ask for quotes: itemised prices for a basket, delivered. | POST /v1/quotes |
order:write | Place orders from quotes, and cancel them or one of their shipments. | POST /v1/orders, POST /v1/orders/{id}/cancel, POST /v1/orders/{id}/shipments/{shipment_id}/cancel |
order:read | Read your orders, their shipments and tracking. | GET /v1/orders, GET /v1/orders/{id} |
webhooks:write | Register, change and delete webhook endpoints, read their deliveries and send one again. | /v1/webhook-endpoints and below |
complaint:write | Report a problem a shopper found with a line of one of your orders once it has left its site (allergen, label, safety, damaged, missing or other), and follow what Kiuki decides. | POST /v1/complaints, GET /v1/complaints/{id} |
GET /v1/markets and GET /v1/whoami work with any valid key. whoami says which organisation the key acts for, its scopes, and whether it is a sandbox key.
No key can approve anything: refunds, for one, need two different people at Kiuki. A program can ask; only people approve.
Plain refusals
A request without a valid key (none, a mistyped one, a revoked one) gets 401:
{"error": "not_signed_in", "message": "That API key isn't valid: it is mistyped, or it was revoked. Send a key that works."}
A valid key that can't do something gets 403, and the message names what is missing:
{"error": "forbidden", "message": "This key can't place orders: it needs the order:write scope."}
The same 403 comes for every request while your organisation isn't approved yet or is suspended, and for a key of another Kiuki app (a seller's or a site's).