Skip to main content
The External API reads and writes protected health information (PHI): patient demographics, documents, clinical notes, eligibility results and prior-auth requests. Treat every key and every response accordingly.
Use the API with real patient data only under a signed business associate agreement (BAA) with HealOS. Contact your HealOS account team to put one in place before you go live.

​
API keys

  • Who can create keys. Only organization admins, in Account Settings → API Keys at app.healos.ai/account-settings.
  • One organization per key. A key reads and writes only the organization it was created in, across every provider in it.
  • Shown once. HealOS stores only a hash of the key. If you lose it, create a new one.
  • Tied to its creator. A key works only while the admin who created it is still an admin of the organization. Removing or demoting that admin turns their keys off (401). Create production keys from an admin account that will stay in place.
  • Recognizable. Keys start with hlsk_, so secret scanners and code review can spot a leaked one.

​
Store keys safely

  • Keep keys in a secrets manager or environment variables on your server. Never put them in source code, browser or mobile apps, logs, tickets or chat.
  • Always call https://api.healos.ai. A request to http:// sends the key unencrypted before it is redirected.
  • Use one key per integration or environment, with a clear label, so you can revoke one without breaking the others.

​
Give each key the narrowest scopes

Choose only the scopes the integration needs. A reporting job that reads notes needs notes:read and nothing else. Avoid * (full access) outside short-lived testing.

​
Set an expiry

When you create a key, choose an expiry (7 days, 30 days, 90 days, 1 year, a custom date, or never). Prefer an expiry for any key that leaves your own servers, for example on a contractor’s machine. An expired key returns 401.

​
Rotate a key

1

Create the new key

Create a key with the same scopes and a new label, for example “EHR sync (2026-11)”.
2

Deploy it

Put the new key in your secrets store and roll it out. Call GET /me with it to confirm the organization and scopes.
3

Revoke the old key

Check the Last used column on the API Keys page has stopped moving for the old key, then revoke it. Revocation takes effect immediately.

​
If a key leaks

Revoke it at once in Account Settings → API Keys, create a replacement, and tell us at support@healos.ai. Don’t wait to confirm misuse first.

​
Handling PHI from the API

  • Store responses as PHI. Notes, transcripts, documents, eligibility results and prior-auth requests all identify a patient.
  • Log ids, not content. Log HealOS ids and your external_id values, never names, dates of birth, note text or eligibility results.
  • Webhooks carry ids, not content. Webhook payloads hold identifiers and a URL to fetch; the content stays behind the authenticated API. Protect your webhook endpoint with a secret header and HTTPS.
  • Test with fake data. Build in a test organization with made-up patients.
  • Delete what you no longer need. Deleting a patient through the API permanently removes them with their sessions and notes.

​
AI tools and these docs

Never paste API keys or real patient data into the docs search, the docs assistant, or any AI chat tool. Use placeholders such as hlsk_... and made-up patients when you ask for help. See Docs for AI agents.