> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medlistiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Bearer API keys. How to create, rotate, and revoke.

MedListIQ uses **Bearer API keys**. Every request to `/v1/*` must include one:

```http theme={null}
Authorization: Bearer ml_abc123...
```

All keys have the same capabilities — there is no separate test/live split.
Use your Free-tier key to build and verify your integration, then upgrade
when you're ready to ship. Rate limits and monthly caps are enforced per
organization, not per key, so minting multiple keys doesn't extend your
allowance — it's just a way to isolate keys per service or environment.

Keys are scoped to an organization. Every request is attributed to the org
that minted the key — that's what drives rate-limit and monthly-cap enforcement.

## Creating a key

1. Sign in to the [portal](https://medlistiq.com)
2. Go to [Dashboard → API Keys](https://medlistiq.com/dashboard/keys)
3. Click **Create key**, give it a name (e.g. `Production 2026`)
4. **Copy the key immediately** — it's shown exactly once. Store it in a password
   manager or environment variable.

<Warning>
  The full key is never retrievable after the creation dialog closes. If you
  lose it, revoke it and mint a new one.
</Warning>

## Rotating keys

Best practice for production: rotate keys quarterly or on any suspected leak.

1. Create a new key
2. Deploy the new key to your production environment
3. Verify traffic is flowing using the new key (check the old key's **Last used**
   timestamp — should stop updating)
4. **Revoke the old key** from the portal

Revocation propagates within \~60 seconds (we cache auth lookups in-process).

## Error responses

<ResponseExample>
  ```json 401 Unauthorized (missing key) theme={null}
  { "detail": "missing API key" }
  ```
</ResponseExample>

<ResponseExample>
  ```json 401 Unauthorized (invalid / revoked key) theme={null}
  { "detail": "invalid or revoked API key" }
  ```
</ResponseExample>

## Security notes

* **Never commit keys to source control.** Use environment variables or a secret
  manager (Vercel envs, Doppler, 1Password, AWS Secrets Manager, etc).
* **Never expose secret keys to the browser.** Our keys are server-side only —
  don't ship them in a bundle or load them client-side.
* **One key per environment** is a reasonable minimum; one key per deployed
  service is even better (so you can isolate blast radius on a rotation).