Authentication
Every endpoint except /v1/health requires an API key.
The header
X-API-Key: kn_...
Keys are verified by SHA-256 hash against the key registry. The raw key is never stored, only its hash and a prefix.
Key format
A key starts with kn_ followed by a random token, for example kn_b3e29753...5190. There is no separate test prefix: the same key works against the live endpoints from any environment.
Scopes and limits
- Each key carries scopes (for example
read) and a per-minute rate limit. - A key can be revoked at any time, and revocation is immediate.
- Every request is metered per key: endpoint, units and timestamp.
Browser and CORS
The API is server-to-server by design: it sends no Access-Control-Allow-Origin header and does not answer OPTIONS preflight requests. Keep the key on your backend and proxy requests from your own origin. Do not call the API directly from browser JavaScript with a key embedded in the page.
Failures
# missing header
401 {"detail":"missing X-API-Key header"}
# unknown or revoked key
401 {"detail":"invalid or inactive API key"}