Every request to the Kanal API is authenticated with an API key passed in the Authorization header.
Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1ZThe key is a 24-character token. It has no prefix: pass it exactly as it appears in the app. All requests must be made over HTTPS.
Creating an API key
Go to Settings then API Keys.
Click Add API key, give it a descriptive name (for example
production-shop), then confirm with Create.Copy the key immediately into your password manager or secret vault.
You can create several keys, find them in the My API keys table, and delete any of them at any time. Deletion is immediate and irreversible.
Keeping your keys secure
Keep your keys server-side only. Never embed them in a browser, a mobile app, or any environment controlled by the end user, and never commit them to a public repository. If a key leaks, delete it from Settings > API Keys and generate a new one.
Your store_id
Commerce API endpoints contain a numeric store_id in their path. It identifies the store the data belongs to. If you do not know it, ask your Kanal contact.
A request is authorized when the team that owns the key also owns the store targeted in the URL. Keys created from Settings > API Keys cover the whole team. Kanal can also scope a key to a single store: it will then only work for that store_id. Any other combination returns a 403, which guarantees a key can never write to a store outside its team.
Messaging API endpoints do not take a store_id: the key itself determines the sending WhatsApp number.
Authentication errors
Situation | Code | Response |
|---|---|---|
Authorization header missing |
|
|
Unknown or deleted key |
|
|
Valid key but not authorized for this store |
|
|
Unknown store_id, or store paused |
|
|
Team without an active subscription (Messaging API) |
|
|
Verifying your setup
The simplest call to validate the key, the store and the authorization all at once is a customer upsert. A 2xx response confirms everything is correct:
curl -X POST https://api.getkanal.com/api/v1/stores/123/customers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone": "+33612345678", "first_name": "Test" }'To verify a key meant for the Messaging API, call POST /api/v1/me instead: the response returns the WhatsApp number and verified name attached to the key.