Skip to content

Authentication & API Keys

All requests to the Akoole Developer Platform must be authenticated using an API key generated from your merchant dashboard.


  1. Sign in to your merchant dashboard at app.akoole.com.
  2. Open Settings → API Keys (or press Cmd+K and search “API Keys”).
  3. Click “Create API Key”.
  4. Give your key a descriptive name (e.g. ERP Inventory Sync or Custom Storefront).
  5. Select the granular permission scopes required for your integration.
  6. Copy the plain-text API key immediately. For security, the full key is only revealed once.

Keys are formatted with a recognizable prefix:

akoole_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Every request to /developer/api/v1/* must include the following headers:

Header Required Description
Authorization Yes Bearer token format: Bearer <your_api_key>
X-Organisation-Uuid Yes The UUID of your organization (found in Settings → Organisation).
X-Branch-Uuid No Optional UUID of the specific branch context for branch-scoped stock queries.
Accept Yes Must be application/json.
Content-Type For POST/PUT Must be application/json when submitting a request body.
Terminal window
curl -X GET "https://api.akoole.com/developer/api/v1/inventory" \
-H "Authorization: Bearer akoole_live_e3b0c44298fc1c149afbf4c8996fb924" \
-H "X-Organisation-Uuid: 01HZX8M9N1ABCD23EF45GH67JK" \
-H "Accept: application/json"

When creating an API key, assign only the minimum necessary permissions following the principle of least privilege:

Scope Group Description
catalogue.view Catalogue Query products, variants, barcode numbers, and prices.
catalogue.manage Catalogue Create, edit, and archive products and categories.
inventory.view Inventory Read stock on hand, low-stock warnings, and warehouse balances.
inventory.transfer Inventory Initiate and approve stock adjustments or branch transfers.
sales.view Sales Retrieve past sales, checkout summaries, and receipts.
sales.sell Sales Create orders and process checkout sales.
customers.view Customers View customer names, phone numbers, and balances.
customers.manage Customers Create or update customer profiles.

  • Rotate: If you suspect a key has been compromised or need to adhere to a secret rotation schedule, click “Rotate” on the key in your dashboard. A new secret is generated immediately while preserving your existing name and permission scopes.
  • Revoke: Revoking a key permanently invalidates it. Any subsequent API requests using that token will receive 401 Unauthorized.