Authentication
Machine API keys, sandbox vs. live, and how to keep credentials safe.
The neolife API authenticates with a machine API key passed as a bearer token:
curl https://api.neolife.health/v1/orders \
-H "Authorization: Bearer $NEOLIFE_API_KEY"
Key types#
| Prefix | Environment | Notes |
|---|---|---|
nk_sandbox_… |
Sandbox | Resolves only to synthetic patients and a mock pharmacy. Build and test freely. |
nk_live_… |
Live | Operates on real patients and pharmacies. Requires an active agreement. |
Because a sandbox key can never touch a real patient, you can build and verify your entire integration end to end before anything goes live — then swap one environment variable.
Scopes#
Keys are scoped to a set of permissions (for example, creating orders vs. only reading them). Create narrowly-scoped keys per integration so a leaked key has the smallest possible blast radius. You manage scopes when you create the key in the dashboard.
Keeping keys safe#
- Server-side only. Never embed a key in a browser bundle, mobile app, or public repo.
- One key per integration/environment, so you can rotate a single key without downtime elsewhere.
- Rotate on exposure. If a key is ever committed or pasted somewhere shared, revoke it and issue a new one immediately.
Sessions (first-party apps)#
The API also accepts a short-lived session JWT for first-party, user-facing surfaces (the clinic console, the patient portal). Third-party integrations should always use machine API keys, not sessions.
Errors#
A missing or invalid key returns 401; a valid key without the required scope returns 403. See the error model.