Authentication#

Every request to https://api.kenari.dev is authenticated with a kenari API key, sent as a bearer token in the Authorization header:

bash

curl https://api.kenari.dev/v23.0/$PHONE_NUMBER_ID \  -H "Authorization: Bearer $KENARI_API_KEY"

This is the same header and scheme that Meta's Graph API uses. Only the value changes: a kenari key in place of a Meta access token. kenari has no separate API-key header, and it doesn't read keys from query parameters.

Key format#

A key is kn_, then the mode (live or test), then _ and 32 letters and digits:

bash

kn_live_0123456789ABCDEFGHIJKLMNOPQRSTUVkn_test_0123456789ABCDEFGHIJKLMNOPQRSTUV

Part	Example	Notes
Mode prefix	`kn_live_` or `kn_test_`	Tells you at a glance which mode a key is in.
Identifier	`kn_live_01234567`	The first 16 characters. The dashboard shows this plus the last four characters so you can recognise a key.
Secret	the rest	Never shown again after creation.

The examples above are placeholders. A real key is only ever shown once, in the dashboard, right after you create it.

Live and test keys#

	`kn_live_`	`kn_test_`
Works with production numbers	Yes	No
Works with Meta test numbers	Yes	Yes
Requests forwarded to Meta	Yes	Yes, for test numbers only

A test key only works with numbers that Meta reports as test numbers (account_mode SANDBOX). Use it in development and CI, so that code that isn't ready for production can't send from a production number.

If you use a test key on a production number, or on a WABA that has any production number connected, kenari returns 401:

json

{  "error": {    "message": "Test keys only work with sandbox numbers.",    "type": "KenariAuthException",    "code": 1001,    "fbtrace_id": "req_..."  }}

Creating keys#

Create keys in the dashboard under API Keys. Each key has a name (1–60 characters) and a mode. The full key is shown once, when you create it. kenari keeps only a keyed hash, so a lost key can't be recovered. Create a new one instead.

An account can have up to 20 active keys. Use separate keys per service or environment, so you can revoke one without affecting the others.

Revoking and rotating#

To revoke a key, open API Keys, find the key and confirm Revoke. Revocation takes effect immediately, and later requests with that key get 401.

To rotate a key without downtime:

Create a new key with the same mode.
Deploy it to your service alongside the old one, then switch traffic to the new key.
Check the old key's Last used time in the dashboard. When it stops moving, revoke the old key.

Authentication errors#

All key failures return 401 with KenariAuthException and code 1001:

Situation	Status	`error.message`
No `Authorization` header, or not `Bearer <key>`	`401`	`Invalid or missing API key.`
Key isn't in the `kn_live_`/`kn_test_` format	`401`	`Invalid or missing API key.`
Unknown or revoked key	`401`	`Invalid or missing API key.`
Test key on a production number	`401`	`Test keys only work with sandbox numbers.`

kenari deliberately returns the same response for a revoked key as for an unknown one.

Authentication happens before anything else is checked. A valid key on a suspended account, or one without an active subscription, gets 402 with KenariBillingException instead. See Errors.

Keep keys secret#

Only call kenari from your server. A key in a web page, browser extension or mobile app can be extracted by anyone who uses it.
Keep keys out of source control. Load them from environment variables or a secret manager.
Don't log the Authorization header. Log the key's first 16 characters if you need to tell keys apart.
Use a test key wherever production access isn't needed.