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

# HIPAA onboarding: from BAA to audit-ready

> Sequence a healthcare tenant from signing the BAA to PHI audit-ready — enable HIPAA mode, restrict roles and API scopes, set retention, read the PHI access log, and export the evidence binder.

# HIPAA onboarding: from BAA to audit-ready

The [HIPAA controls](/compliance/hipaa) reference explains what each control does. This guide puts them in order — the sequence that takes a healthcare workspace from "we handle PHI" to "we can show an audit trail" without tripping the `422 HIPAA_BAA_REQUIRED` send gate — one of the [send gates](/compliance/send-gates) that check sender compliance before a message or call dispatches.

The order matters. HIPAA mode cannot be enabled before the BAA is executed, PHI sends are rejected until it is, and retention only protects data once it is configured. Follow the steps top to bottom.

## 1. Execute the BAA

Nothing else unblocks until the Business Associate Agreement (BAA) is executed. Two gates read BAA status directly:

* **Enabling HIPAA mode** returns `403 Forbidden` while BAA status is not `executed`.
* **Any PHI send** is rejected with `422 HIPAA_BAA_REQUIRED`.

Execute it through the **Compliance → BAA** pane in the dashboard, or via API:

1. `POST /api/v1/compliance/baa/require` — attests PHI is in scope and moves the organization from `not_required` to `pending` (owner role).
2. `POST /api/v1/compliance/baa/execute` — records the type-the-name e-signature; the organization is stamped `executed` (owner role).
3. `GET /api/v1/compliance/baa/` — confirm `baa_status` is `executed` and note `days_until_expiry`; an executed BAA expires after its one-year term.

The BAA lifecycle, the legacy-mirror caveat, and the full request shapes are documented under [BAA](/compliance/hipaa#5-business-associate-agreement-baa).

## 2. Enable HIPAA mode

With the BAA executed, turn on the per-organization HIPAA flag. HIPAA mode is a per-organization feature flag that activates five controls at once — encryption at rest, access controls, PHI audit logging, enforced retention, and BAA tracking.

* **Dashboard:** **Settings → Compliance → HIPAA Mode Toggle**.
* **API:**

```bash theme={null}
PUT /api/v1/settings/hipaa
{
  "enabled": true
}
```

Enabling is a single call — it tightens the workspace's posture, so no re-authentication challenge is required. Disabling is destructive and does require one; that flow is documented under [Disabling HIPAA Mode](/compliance/hipaa#6-disabling-hipaa-mode).

## 3. Restrict roles and API scopes to minimum necessary

HIPAA's *minimum necessary* standard is **your** responsibility — it sits on the customer side of the [shared-responsibility table](/compliance/hipaa#shared-responsibility). Orbit's controls today are coarse, so provision for it honestly:

* Use the **`billing` role** for staff who only need financial surfaces. Billing members are confined to billing, pricing, and usage — they receive `403` on message-content endpoints.
* Keep everyone else's need-to-read in mind: `owner`, `admin`, `developer`, and `viewer` can all read message content today, and every read lands in the PHI access log.
* Mint API keys with only the scopes the integration needs, and grant `messages:read` only to services that genuinely read PHI-bearing message content.

> **Known limitation:** Orbit does not currently restrict message-content reads to a narrower set of roles beyond the billing confinement, and the message read endpoints (`GET /messages`, `GET /messages/{id}`) do not require an operator-supplied reason code. Meet the minimum-necessary standard by provisioning workspace membership and API-key scopes so only staff who need PHI can reach those endpoints. If your program requires per-role read restriction on message content, contact [compliance@devotel.io](mailto:compliance@devotel.io) before relying on it.

## 4. Configure data retention

Set the retention window before PHI accumulates beyond it.

* **Dashboard:** **Settings → Compliance → HIPAA → Data Retention**.
* **API:**

```bash theme={null}
PUT /api/v1/settings/hipaa
{
  "data_retention_days": 365
}
```

The default is 365 days and the configurable range is 30–3,650 days. A background job scans for expired message content, call recordings, and media attachments and deletes them. Audit logs and PHI access logs are retained independently of this policy — the deletion clock does not erase your evidence trail.

If you record calls, pin the voice region to match your residency obligations at the same time — see [Voice Data Residency & Retention](/compliance/voice-data-residency) for the residency knob that keeps recordings, voicemail, and live media in one region.

## 5. Verify the configuration

Confirm the flag and retention landed the way you intended:

```bash theme={null}
GET /api/v1/settings/hipaa
```

Check `enabled` and `data_retention_days` in the response.

> The response also carries an `encryption_algorithm` field. It is **reporting-only**: it reflects the platform's at-rest encryption standard (Google-managed AES-256 on Cloud SQL), not a per-organization application-layer cipher. Devotel does not currently perform per-organization application-layer encryption of message bodies, so do not cite this field to an auditor as evidence that message bodies are individually encrypted at the application layer.

## 6. Read the PHI access log

Once HIPAA mode is on, every access to PHI-containing data is written to an append-only audit log. Each entry records the user, the resource, the reason (`read` is recorded automatically on message reads), and the timestamp.

```bash theme={null}
GET /api/v1/settings/hipaa/phi-access-log
```

The log keeps up to 10,000 entries per organization with the oldest rotated out, is accessible to `owner` and `admin` roles via the dashboard or API, and can be exported for external audits. Review it on a schedule early — it is how you demonstrate that access follows the role and scope decisions you made in step 3.

## 7. Export the HIPAA evidence binder

When you need to show posture to an auditor or a buyer's procurement team, generate the HIPAA pack of the [evidence binder](/compliance/evidence-binder) from **Settings → Compliance → Binder**. The HIPAA framework assembles PHI access logging, BAA posture, and your configured retention into a signed, download-ready pack; every generation is recorded in your audit log, and the download link expires after 24 hours.

## Healthcare activation bundle

The [compliance plugin marketplace](/compliance/plugin-marketplace) ships a **HIPAA healthcare** activation bundle that provisions a draft compliance profile, draft campaigns, a vertical-tuned AI agent, and an opt-in flow configuration in one call. It is a starting scaffold, not a substitute for this sequence: activating the bundle never executes the BAA, never enables HIPAA mode, and never places a send. Run steps 1–6 above first, then activate the bundle and work its go-live checklist from draft to production.

## Order-of-operations checklist

* [ ] BAA executed and `baa_status` confirmed as `executed` — *owner role*
* [ ] HIPAA mode enabled via the toggle or `PUT /settings/hipaa` — *owner role*
* [ ] Membership trimmed to minimum necessary; `messages:read` scoped only to keys that need it — *administrator*
* [ ] `data_retention_days` set to your policy window — *administrator*
* [ ] Voice region pinned if your residency obligations restrict where recorded audio may live — *administrator*
* [ ] `GET /settings/hipaa` verified, with `encryption_algorithm` treated as reporting-only — *compliance officer*
* [ ] PHI access log reviewed on a schedule — *compliance officer*
* [ ] HIPAA evidence binder generated and handed off through the 24-hour link — *compliance officer*