Skip to content

Shop API authentication

For Owner, ManagerAll plans

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).

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

Send the secret once, as either:

  1. Authorization: Bearer akoole_…
  2. 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.

Terminal window
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"
Terminal window
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 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

These scopes are rejected at create/update time:

  • org.api_keys.manage
  • org.billing
  • org.roles.manage
  • org.members.manage
  • org.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.

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
Terminal window
# 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"
Terminal window
# Update scopes without rotating
curl -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"
  • Optional expires_at (ISO-8601, must be in the future when set). Expired keys authenticate as 401.
  • Revoked keys authenticate as 401.
  • last_used_at updates when a key successfully authenticates.

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
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