> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security and HIPAA

> Handle API keys, scopes and protected health information safely

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.

> [!WARNING]
>
> 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](https://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](https://docs.healos.ai/authentication.md#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`](https://docs.healos.ai/api-reference/account/describe-the-calling-api-key) 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](mailto: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](https://docs.healos.ai/webhooks.md) 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](https://docs.healos.ai/test-mode.md) with
  made-up patients.
* **Delete what you no longer need.** [Deleting a patient](https://docs.healos.ai/api-reference/patients/delete-a-patient.md)
  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](https://docs.healos.ai/ai-agents.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.