Kanal APIAuthentication
How to create an API key and authenticate your requests.
Every request is authenticated with a Bearer API key sent in the
Authorization header:
Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1ZThe key is a 24-character token. There is no prefix — send it exactly as shown in the app.
Creating an API key
API keys are managed from the Kanal app:
- Go to Settings → API Keys.
- Click Add API key, give it a name (e.g.
production-shop), and Create. - The key is shown once in the "Store your new API key" dialog. Copy it immediately into a password manager or your secrets store — you won't be able to view it again.
You can create several keys, see them in the My API keys table, and delete any key at any time (deletion is immediate and irreversible).
Keep keys server-side. Never ship them in a browser, mobile app, or any client the customer controls. If a key leaks, delete it in Settings → API Keys and create a new one.
Your store_id
Every endpoint path contains a numeric {store_id}. It identifies which store
the data belongs to. Ask your Kanal contact for the store_id matching your
shop if you don't have it.
Store authorization
A request is authorized when the key's team owns the store in the URL
(keys created from Settings → API Keys are team-wide). Keys can also be
restricted to a single store by Kanal — in that case they only work for that
one store_id.
Any other combination returns 403, so a key
can never write data to a store outside its team.
Auth failure modes
| Situation | Status | Body |
|---|---|---|
No Authorization header | 401 | { "error": "API key is missing" } |
| Unknown / deleted key | 401 | { "error": "Invalid API key" } |
| Valid key, not authorized for this store | 403 | { "error": "API key does not authorize this store" } |
store_id unknown or store paused | 404 | { "error": "Store not found or paused" } |
See Errors for the full reference.
Verifying your setup
The cheapest authorized call is a customer upsert. A 2xx confirms the key,
the store, and the authorization are all correct:
curl -X POST https://api.getkanal.com/api/v1/stores/123/customers \
-H "Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1Z" \
-H "Content-Type: application/json" \
-d '{ "phone": "+33612345678", "first_name": "Test" }'