Authentication & API Keys
All requests to the Akoole Developer Platform must be authenticated using an API key generated from your merchant dashboard.
Obtaining an API Key
Section titled “Obtaining an API Key”- Sign in to your merchant dashboard at
app.akoole.com. - Open Settings → API Keys (or press
Cmd+Kand search “API Keys”). - Click “Create API Key”.
- Give your key a descriptive name (e.g.
ERP Inventory SyncorCustom Storefront). - Select the granular permission scopes required for your integration.
- 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxRequired Request Headers
Section titled “Required Request Headers”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. |
Example cURL Request
Section titled “Example cURL Request”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"Permission Scopes
Section titled “Permission Scopes”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. |
Rotating & Revoking Keys
Section titled “Rotating & Revoking Keys”- 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.