Get started

Authentication

Every request carries one of the company’s API keys, in a header.

Send the key on every request, in either header. Both are the same key; use whichever your HTTP client makes easier.

http

X-Api-Key: kwn_live_…
# or, the same key:
Authorization: Bearer kwn_live_…

A key starts kwn_live_. A value that does not is refused before it is looked up.
A key reaches /api/v1 only, and only its own company. A user’s sign-in to the KWN app does not open the API, and a key does not open the app.
Requests must use HTTPS.

When a key is refused

Status	Code	Meaning
401	`API_KEY_INVALID`	No key, a wrong one, or one that was revoked.
401	`MERCHANT_INACTIVE`	The company’s account is not active. Every key of it stops with it.
403	`ROLE_TOO_LOW`, `APP_NOT_GRANTED`, `APP_LOCKED`	The key is valid but its scopes, or the company’s plan, do not allow this call. See Scopes.

KWN stores only a SHA-256 hash of a key; the full key is shown once, when it is created. A lost key is replaced, not recovered.
Keep keys in a secret store or environment variable on your server. Never ship one in a mobile app, a browser page or a repository.
Use one key per system, named after it, so one can be revoked without touching the others.
Revoke a key in Settings → Integrations → API keys and it stops at once. The list shows when each key was last used.
Rotate by creating the new key, deploying it, then revoking the old one.