Skip to content
KiukiPlatform
Documentation

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.

ScopeLets the keyEndpoints
catalogue:readRead live listings in a market: packs, labels, prices and availability.GET /v1/catalogue, GET /v1/catalogue/{listing_id}
quote:writeAsk for quotes: itemised prices for a basket, delivered.POST /v1/quotes
order:writePlace 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:readRead your orders, their shipments and tracking.GET /v1/orders, GET /v1/orders/{id}
webhooks:writeRegister, change and delete webhook endpoints, read their deliveries and send one again./v1/webhook-endpoints and below
complaint:writeReport 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).