Shop API authentication
Call Akoole’s shop APIs from a script, accountant tool, or internal service without a staff login.
Create keys in the staff app: API keys (product guide).
Base URL
Section titled “Base URL”Use your environment’s API host, for example:
- Local:
http://api.akoole.localhost - Staging / production: your
api.*host
Module prefixes:
| Area | Prefix |
|---|---|
| Organisation (branches, reports, audit) | /organisation/api/v1 |
| Catalogue | /catalogue/api/v1 |
| Inventory | /inventory/api/v1 |
| Sales | /sales/api/v1 |
| Customers | /customers/api/v1 |
| Purchasing | /purchasing/api/v1 |
| Media | /media/api/v1 |
| Logistics | /logistics/api/v1 |
| Trade | /trade/api/v1 |
| Notifications | /notifications/api/v1 |
| Storefront owner | /storefront/api/v1 |
Authenticate
Section titled “Authenticate”Send the secret once, as either:
Authorization: Bearer akoole_…X-Api-Key: akoole_…
Also send the shop:
X-Organisation-Uuid: <organisation uuid>on shared API hosts, or- Hit the tenant Host (
{slug}.akoole…) when that is how your environment routes shops
The key is already pinned to one organisation. A mismatched X-Organisation-Uuid is rejected.
curl -sS \ -H "Authorization: Bearer akoole_YOUR_SECRET" \ -H "X-Organisation-Uuid: 01HEXAMPLEORGUUID000000000" \ -H "Accept: application/json" \ "https://api.example.com/catalogue/api/v1/products"curl -sS \ -H "X-Api-Key: akoole_YOUR_SECRET" \ -H "X-Organisation-Uuid: 01HEXAMPLEORGUUID000000000" \ -H "Accept: application/json" \ "https://api.example.com/organisation/api/v1/branches"Scopes
Section titled “Scopes”Scopes are the same permission slugs used for staff roles (see Permission glossary).
Grant only what the integration needs. Examples:
| Integration | Typical scopes |
|---|---|
| Read catalogue for sync | catalogue.view |
| Push stock adjustments | inventory.view, inventory.manage |
| Pull receipts | sales.view |
| Online shop ops | storefront.view (and storefront.manage to change settings) |
| Branch list / HQ metrics | org.binoculars, optionally branches.manage |
| Audit export | org.audit.view, org.audit.export |
Forbidden on API keys
Section titled “Forbidden on API keys”These scopes are rejected at create/update time:
org.api_keys.manageorg.billingorg.roles.manageorg.members.manageorg.members.invite
Human-only routes (billing, invites, role writes, API key admin, organisation profile edit) stay on Sanctum staff sessions even if a key somehow listed them.
Manage keys (staff session)
Section titled “Manage keys (staff session)”All management calls need a staff Sanctum bearer token plus org.api_keys.manage.
| Method | Path | Notes |
|---|---|---|
GET |
/organisation/api/v1/api-keys?include_revoked=1 |
List keys (no secrets) |
POST |
/organisation/api/v1/api-keys |
Create - body: name, scopes[], optional expires_at - response includes plain_text once |
PATCH |
/organisation/api/v1/api-keys/{uuid} |
Update name / scopes / expires_at without rotating the secret |
POST |
/organisation/api/v1/api-keys/{uuid}/rotate |
New secret; previous key revoked; response includes plain_text once |
POST |
/organisation/api/v1/api-keys/{uuid}/revoke |
Immediate revoke |
# Create (staff token)curl -sS -X POST \ -H "Authorization: Bearer STAFF_TOKEN" \ -H "X-Organisation-Uuid: ORG_UUID" \ -H "Content-Type: application/json" \ -d '{"name":"CSV bot","scopes":["catalogue.view","sales.view"],"expires_at":"2027-01-01T00:00:00Z"}' \ "https://api.example.com/organisation/api/v1/api-keys"# Update scopes without rotatingcurl -sS -X PATCH \ -H "Authorization: Bearer STAFF_TOKEN" \ -H "X-Organisation-Uuid: ORG_UUID" \ -H "Content-Type: application/json" \ -d '{"scopes":["catalogue.view"]}' \ "https://api.example.com/organisation/api/v1/api-keys/KEY_UUID"Expiry and revocation
Section titled “Expiry and revocation”- Optional
expires_at(ISO-8601, must be in the future when set). Expired keys authenticate as 401. - Revoked keys authenticate as 401.
last_used_atupdates when a key successfully authenticates.
What keys can call
Section titled “What keys can call”API keys work on module routes that use org.actor authentication, including:
- Catalogue, inventory, sales, customers, purchasing, media, logistics, trade, notifications
- Organisation: branches, banks resolve, binoculars / HQ rollup / period reports, role read, permissions catalogue, audit logs
- Storefront owner APIs (settings, orders, discounts, …) when scoped
API keys cannot call:
- Create/list organisations for a user
- Patch organisation branding / custom staff domain
- Billing and referrals
- Invite / manage members or write roles
- Create / rotate / revoke API keys
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
401 |
Missing / invalid / revoked / expired key, or human-only route with only an API key |
403 |
Active key but missing required scope |
404 |
Org header mismatch or unknown tenant |
422 |
Forbidden or unknown scope on create/update |