Authentication
All requests must include a valid API key in the X-API-Key header.
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, list the providers in your organization, and read clinical notes belonging to any member of your org. A single key covers every provider in the organization; you assign records to specific providers with the provider_id field rather than issuing a key per provider.
Scopes
Each API key has a set of scopes that control resource access. Scopes follow a resource:action pattern.
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.
