API keys
If you want to call Karas from your own backend rather than through the widget, you use an API key instead of a widget key. The two are different in kind, not just in name.
How an API key differs from a widget key
An API key is a secret. It is not tied to a domain, it authenticates on its own, and anyone holding it can ask questions against your documentation. Treat it like a password.
A widget key is public and constrained by domain. See Your widget key and domain allowlist.
Where to keep it
In your server's environment or a secret manager. Never in front-end code, never in a repository, never in a mobile app binary — all three are readable by anyone determined to read them.
If you need to make requests from a browser, use the widget key and the allowlist. That is what it is for.
How to use it
Send it in the X-API-Key header on each request. See the
API reference.
What it is scoped to
An API key resolves to your account, and every request made with it is answered from your documentation only. The account is established by the key itself and can never be set in the request body — a body field naming an account is rejected, not quietly ignored, so a key cannot be pointed at anyone else's documentation.
Rotating it
Email support@usekaras.com. We can issue a second key before retiring the first, so you can roll over without downtime.
If you think a key is exposed
Tell us immediately and we will revoke it. Unlike a widget key, an exposed API key is a real incident: it works from anywhere.