# Authentication

The widget authenticates every request with your organisation's API key, sent as the `X-API-Key` header. There is nothing else to set up on your side.

## Obtaining a key

API keys are created in the CareConekt admin portal by your organisation's administrators. Each key:

- is prefixed with `ck_` (for example `ck_91501a75a7e00be5...`),
- is shown once, at creation time,
- belongs to your organisation and is subject to your subscription plan.

Pass it to the widget as `apiKey` in `configure()`.

## Key security

:::{warning}
The key is sent from the visitor's browser, so it is visible to anyone who opens the page's source or the browser's developer tools.

Treat a widget key as a **public client credential**, like a maps API key: use a key created for this purpose, keep it separate from keys used by your servers, and rotate it if it leaks. Your plan's rate limits apply per key.
:::

## Key rotation

1. Create a new key in the admin portal.
2. Update the widget's `apiKey`.
3. Revoke the old key. It stops working immediately.

## What the errors mean

The widget reports problems through the `onError` callback (see [Configuration](configuration.html)):

| Message | Meaning | What to do |
|---------|---------|------------|
| `Invalid API key` | The key is missing, mistyped or revoked | Check `apiKey`; create a new key if the old one was revoked |
| `Access denied — check your subscription plan` | The key is valid but your plan does not include code system search | Contact your administrator about the plan |
| `Rate limit exceeded — try again later` | Your plan's request limit for this key was reached | Wait, or ask about a higher plan |
| `API error: …` | Another error from the service | Retry; contact support if it persists |

The hosted [demo](demo/) is a quick way to check a key: enter it, search for "diabetes", and the output area shows either results or the error message.