Skip to main content
MedListIQ uses Bearer API keys. Every request to /v1/* must include one: 
Authorization: Bearer ml_test_abc123...

​
Test vs live keys

PrefixEnvironmentUse for
ml_test_...Development / sandboxBuilding your integration, testing against fake data
ml_live_...ProductionReal patient data from your production system
Keys are scoped to a Clerk 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
  2. Go to Dashboard → API 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.
The full key is never retrievable after the creation dialog closes. If you lose it, revoke it and mint a new one.

​
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

{ "detail": "missing API key" }

{ "detail": "invalid or revoked API key" }

​
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).