Authentication
All requests must include a valid API key in the X-API-Key header.
curl -H "X-API-Key: hlsk_your_key_here" \
https://api.healos.ai/ext-api/v1/patients
Prerequisites
- You must belong to an organization. If you don’t have one, create one first from the Healos dashboard.
- Only organization admins can create, list, and revoke API keys.
Obtaining an API Key
Create API keys by making an authenticated POST request to /api/v1/ext-api-keys from a logged-in Healos session. You must be an org admin. The response includes the raw key — store it securely, as it cannot be retrieved again.
API keys are prefixed with hlsk_ and are tied to your organization. All data accessed through the key is scoped to your organization — you can read and write patients, appointments, and documents belonging to any member of your org.
Scopes
Each API key has a set of scopes that control resource access. Scopes follow a resource:action pattern.
| Scope | Description |
|---|
* | Full access to all resources |
patients:read | Read patient data |
patients:write | Create, update, delete patients |
appointments:read | Read appointments |
appointments:write | Create, update, delete appointments |
documents:read | Read documents |
documents:write | Upload and delete documents |
GET and HEAD requests require read scopes. All other methods (POST, PATCH, DELETE) require write scopes.
Key Expiration and Revocation
- Keys can have an optional expiration timestamp set at creation.
- Keys can be revoked at any time.
- Expired or revoked keys return
401 Unauthorized.
Security Best Practices
- Use the narrowest scopes needed for your integration.
- Set an expiration date on keys used in less-trusted environments.
- Rotate keys periodically and revoke old ones.
- Never expose keys in client-side code or public repositories.