API authentication and keys

Every request to the Kanal API is authenticated with an API key passed in the Authorization header. We recommend also adding the Accept: application/json header, so that you receive JSON responses, including for errors.

Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1Z
Accept: application/json

The key is a 24-character token. It has no prefix: pass it exactly as it appears in the app.

Creating an API key

1. Click your team name, then Settings.

2. Open Developers > API Keys.

3. Click Add API key, give it a descriptive name (for example production-shop), then confirm with Create.

4. Copy the key immediately into your password manager or secret vault.

The full key is shown only once, when it is created. After that, it stays visible in masked form, with only its last 4 characters. If you lose it, delete it and create a new one.

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.

What the key is attached to

An API key is attached to a WhatsApp number, not to the team. If your team uses several numbers, each number has its own list of keys. The key's team is the one that owns the WhatsApp Business account this number belongs to.

• Messaging API: the key itself determines the sending WhatsApp number. These endpoints do not take a store_id.

• Commerce API: the key gives access to the stores of that team.

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. If a key leaks, delete it from Settings > Developers > API Keys and generate a new one.

Your store_id and store-scoped keys

Commerce API endpoints contain a numeric store_id in their path. It identifies the store the data belongs to.

You manage this information yourself in Settings > Stores, on a store of the Custom store type:

• the Guide tab shows the store's store_id: it is the number that follows /stores/ in the cURL example;

• the API & ingestion tab provides an API ingestion key limited to that single store, which you can regenerate or revoke. Like an API key, it is shown in full only once: copy it right away.

The full walkthrough is in Connect a non-Shopify store (custom store).

A request is authorized when the key's team owns the store targeted in the URL. An ingestion key only works for its own store's store_id. Any other combination returns a 403: a key can never write to a store outside its team.

An ingestion key also works on the Messaging API: it can send messages, not only store data. Protect it like a regular API key.

Authentication errors

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 "Accept: application/json" \
  -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.