Skip to content

Authentication

The Levelcast API supports two authentication methods. They are not interchangeable: session cookies work with the dashboard routes, API keys work with the public (/api/v1/public/*) routes.

Session cookies (dashboard)

The web dashboard authenticates via session cookies managed by Better Auth. Cookie-based auth is handled automatically by the browser. Use it for the dashboard routes such as POST /api/v1/patients or POST /api/v1/apiKeys (key management).

API Keys

For programmatic access (integrations, scripts, MCP), generate an API key from the dashboard under Settings → API Keys and link at least one patient to it.

Include the key in every request using the X-API-KEY header:

GET /api/v1/public/patients
X-API-KEY: lc_your_key_here

Only the x-api-key header is accepted. A query parameter does not work.

Terminal window
curl "https://api.levelcast.org/api/v1/public/patients" \
-H "X-API-KEY: lc_your_key_here"

Key scopes

ScopeAllows
readGET requests (patients, readings, events, stats, exports status…)
writeEverything read allows, plus POST/PUT/PATCH/DELETE (create readings, events, exports, channels, rules via MCP…)

GET requests require the read scope; any other method requires write. There is no admin scope — API keys never grant admin access.

Patient scoping

Keys are linked to a set of patients. Endpoints under /api/v1/public/patients/:patientId/... return 403/404 for patients not linked to the key. A few endpoints are user-scoped instead (channels, frames, exports, shared links) and work with any key owned by the user.

See API Keys and the API reference for the full endpoint list.