Skip to content

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

PlanKeys
Free1
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[] } — validates validateUserOwnsPatient for each ID. The full key value is shown only once.
  • List: GET /api/v1/apiKeys?search=&filters= — paginated, grouped by apiKeyPatient.
  • Toggle: PATCH /api/v1/apiKeys/:id/toggle
  • Delete: DELETE /api/v1/apiKeys/:id — also clears apiKeysCache.

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/patients
X-API-KEY: lc_your_key_here
Terminal window
curl "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:

Terminal window
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.