API Keys
API Keys are 32-char tokens (lc_...) scoped to a set of patients. They authenticate the public REST API (/api/v1/public/*) and the MCP server. Key management (create/list/toggle/delete) uses the session-authenticated dashboard routes (/api/v1/apiKeys) instead.
Limits
| Plan | Keys |
|---|---|
| Free | 1 |
| Pro/Clinic/Founder | ∞ |
Enforced at POST /api/v1/apiKeys via canCreateApiKey. Returns 402 LIMIT_REACHED with plan/limit/used.
Managing keys (dashboard, session auth)
- Create:
POST /api/v1/apiKeys { name, patientIds[] }— validatesvalidateUserOwnsPatientfor each ID. The full key value is shown only once. - List:
GET /api/v1/apiKeys?search=&filters=— paginated, grouped byapiKeyPatient. - Toggle:
PATCH /api/v1/apiKeys/:id/toggle - Delete:
DELETE /api/v1/apiKeys/:id— also clearsapiKeysCache.
UI: ApiKeysPage.vue shows the usage stat card, an upsell modal at the limit, and UserApiStats + ApiUsageGuide.
Using keys (public API)
GET /api/v1/public/patientsX-API-KEY: lc_your_key_herecurl "https://api.levelcast.org/api/v1/public/patients" \ -H "X-API-KEY: lc_your_key_here"GET requires the read scope; POST/PUT/PATCH/DELETE require write. Patient-scoped endpoints return 403/404 for patients not linked to the key.
Check a key’s usage without touching patient data:
curl "https://api.levelcast.org/api/v1/public/keys/usage" \ -H "X-API-KEY: lc_your_key_here"Exceeding the rate limits returns 429 with a Retry-After header.