> ## 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 mode first enablement — operator runbook

> The sequenced runbook for a first HIPAA enablement: execute the BAA, enable HIPAA mode, designate PHI audiences, set the retention window, and verify through the compliance-health score — plus the boundaries of what the toggle does and does not certify.

# HIPAA mode first enablement — operator runbook

The [HIPAA controls](/compliance/hipaa) reference describes every HIPAA
surface in detail, and the [HIPAA posture guide](/compliance/hipaa-posture-guide)
explains how the controls compose into a posture. Neither answers the
operator question for a workspace doing this the first time: **in what
order do I flip the tenant-owned toggles?** This runbook is that order —
four tenant-owned settings sequenced into a first enablement, with the
response you should see after each step and the verification pass at the
end.

Everything here is a **tenant-owned control**: you decide PHI is in
scope, you execute the agreement, you designate the audiences, you pick
the retention window. The platform enforces what you set — it does not
certify the result. The boundaries section at the bottom is written for
the person who has to explain that distinction to an auditor.

All calls run against `https://api.orbit.devotel.io/api/v1` with an
`X-API-Key` header. Steps 1 and 2 need an **owner** key; the read-back
checks work with an owner or admin key. The same moves are available in
the dashboard under **Settings → Compliance**; the API is shown because
it is scriptable and the responses are deterministic.

***

## 1. Who needs these steps, and why the order is fixed

Run this sequence if your workspace sends or stores Protected Health
Information (PHI) through Orbit — appointment reminders, care-team
follow-ups, intake transcripts — over SMS, WhatsApp, voice, fax, or any
other channel. If no PHI enters your traffic, none of this applies: the
default attestation is `not_required` and the gates stay open.

The order is not advisory — one hard dependency fixes it:

* **BAA first.** HIPAA mode cannot be enabled while your organization
  is not on an `executed` [Business Associate Agreement](/compliance/baa)
  (BAA): the enable call returns `403 Forbidden` until the BAA is
  signed. Separately, **any PHI send** is rejected at send time with a
  `422 HIPAA_BAA_REQUIRED` envelope while PHI is in scope without an
  executed, in-term BAA — that is the only fail-closed gate in the
  HIPAA surface, and it exists so PHI traffic cannot leave the platform
  before the agreement it travels under exists. (The gate's verdict and
  its fail-closed behavior are summarized in the
  [posture FAQ](/compliance/posture-faq#what-is-fail-closed-by-design).)
* **Mode before the rest.** Designating audiences and setting retention
  before HIPAA mode is on are inert writes — the data is recorded, but
  the enforcement (the campaign launch precheck, the deletion job)
  activates with the mode. Sequence audiences and retention *after*
  the enable so nothing flows through a half-configured posture — you
  show as enabled only when the controls behind the toggle are set.

Skip the sequencing in two places and you pay for it the same day:
enable without a BAA is a `403`, and a campaign launch against a
designated PHI audience without an executed BAA is a `422` at launch.

***

## 2. The runbook

Five steps, in order. Each lists the call, the expected success
response, and the failure you will see if you run it out of order.

### Step 1 — Execute the Business Associate Agreement

Move the organization through the BAA lifecycle: attest PHI is in scope,
then execute the type-the-name e-signature. Both are owner-only.

```bash theme={null}
# 1a. Attest that PHI is in scope (moves not_required -> pending)
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/baa/require \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Clinic messaging will carry PHI" }'

# 1b. Execute with a type-the-name e-signature (owner only)
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/baa/execute \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "Ada Lovelace",
    "signer_email": "ada@clinic.example",
    "typed_attestation": "Ada Lovelace"
  }'
```

Expect `baa_status: "executed"` with a one-year term and a
`days_until_expiry` countdown. Re-execution opens 60 days before expiry.
The lifecycle, decline/revert controls, and the re-execution window are
the [BAA page](/compliance/baa)'s subject — this runbook only fixes
where they sit in the sequence.

### Step 2 — Enable HIPAA mode

Owner-only, and gated on step 1:

```bash theme={null}
curl -X PUT https://api.orbit.devotel.io/api/v1/settings/hipaa \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

Expect `enabled: true` with `enabled_at` stamped and
`data_retention.enabled: true` at the 365-day default. If the BAA is
not `executed`, the same call returns `403 Forbidden` — go back to
step 1; the toggle does not open early, and there is no override.

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

### Step 3 — Designate PHI-adjacent audiences

Register the contact lists and segments whose members carry PHI — for
example, patients opted into treatment outreach. Designation lives on
the audience, not on any individual campaign: once a campaign's
audience resolves to a designated list or segment, the launch precheck
requires the executed BAA from step 1 before the campaign can leave
draft.

```bash theme={null}
curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/hipaa/phi-audiences \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience_ids": ["list_9f2c1a", "seg_4b7e20"] }'
```

The PUT is a **full replacement** of the designated id set — to lift a
designation, PUT the registry without that id; an empty array clears it.
Endpoint semantics, the server-side registry ceiling, and the atomic
write guarantee stay on the
[PHI-adjacent audience designations](/compliance/phi-audiences) page;
they are deliberately not re-documented here.

### Step 4 — Set the data-retention window

Pick the deletion window your policy requires before PHI accumulates
beyond it. `data_retention_days` accepts 30–3,650; the enable call in
step 2 already armed retention at the 365-day default, so this step is
only needed if your window differs:

```bash theme={null}
curl -X PUT https://api.orbit.devotel.io/api/v1/settings/hipaa \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "data_retention_days": 90 }'
```

An automated background job deletes expired message content, call
recordings, and media attachments. Audit logs and PHI access logs are
retained independently — the deletion clock does not erase your
evidence trail. The per-domain redaction and purge surface that
complements this window is documented under the
[data-retention policy](/compliance/data-retention-policy) page.

### Step 5 — Verify and read the score lift

The full verification checklist is section 3 — run it now, before you
consider the enablement done. The last check, the
[compliance-health](/compliance/compliance-health) score, is the single
number you can watch move: before enablement, a workspace with HIPAA
posture opens unresolved (unexecuted BAA, mode off, no retention window)
reads as an open risk surface there; after this sequence, the posture
resolves and the score reflects it.

***

## 3. Verification checklist

Run these four checks in order after step 5. Each is an owner-or-admin
read against the response you should expect on a correct enablement.

1. **The HIPAA status object agrees with what you set.**
   `GET /api/v1/settings/hipaa` (a `PUT` echoes the same shape, so
   your last write already returned it). Check the fields that prove
   the sequence landed:

   ```json theme={null}
   {
     "data": {
       "enabled": true,
       "enabled_at": "2026-09-25T09:14:40.118Z",
       "last_enabled_at": "2026-09-25T09:14:40.118Z",
       "disabled_at": null,
       "baa_status": "executed",
       "hipaa_required": true,
       "data_retention": { "enabled": true, "days": 90 },
       "encryption_algorithm": "AES-256-GCM",
       "phi_access_log_count": 0
     },
     "meta": { "request_id": "…", "timestamp": "…" }
   }
   ```

   `enabled` is `true`, `baa_status` is `executed`,
   `data_retention.days` matches your window, and `disabled_at` is
   `null`. Treat `encryption_algorithm` as **reporting-only** — it
   reflects the platform's at-rest encryption standard, not a
   per-organization application-layer cipher; do not cite it to an
   auditor as evidence of application-layer body encryption. (The
   caveat in full: [HIPAA controls — encryption at rest](/compliance/hipaa#1-encryption-at-rest).)

2. **PHI access logging is actually recording.** With the mode on, every
   access to PHI-containing data appends to the PHI access log. Exercise
   a message read, then page the log:

   ```bash theme={null}
   curl "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50" \
     -H "X-API-Key: $ORBIT_KEY"
   ```

   Expect entries shaped like
   `{ "id", "userId", "resource": "message:msg_…", "reason": "read", "accessedAt" }`
   with `has_more` and `total` for pagination. A first enablement with a
   nonzero `phi_access_log_count` in check 1 and entries here is the
   proof the audit surface is live; `phi_access_log_count: 0` is only
   expected before any PHI-bearing access has happened.

3. **The designated-audience gate trips the way you intended.** Attempt
   a launch of a draft campaign against one of your designated lists.
   With the BAA executed it launches normally; the check worth running
   once is reading the advisory warning in the campaign wizard's
   audience step (*"This audience is designated as PHI-adjacent…"*) so
   you know what your operators will see. The precheck's hard refusal
   envelope is `422 HIPAA_BAA_REQUIRED`, and it appears only if the BAA
   lapses — if you ever see it after enablement, the BAA has expired,
   not the gate miswired.

4. **The compliance-health score moved.**
   `GET /api/v1/compliance/health?window_days=30` returns the
   organization rollup — the same number at the top of the dashboard
   panel. Compare the score before you started this runbook with the
   score after the BAA, mode, designation, and retention are set: an
   open HIPAA posture is scored as an unresolved risk surface, and the
   sequence resolves it. The score bands and the four risk factors
   behind the rollup are on the
   [compliance health scores](/compliance/compliance-health) page; the
   alerting thresholds that watch the score continuously are in the
   [compliance-health alerting runbook](/guides/compliance-health-alerting-runbook).

Order-of-operations summary, with the role that owns each step:

* [ ] BAA executed, `baa_status: "executed"` confirmed — *owner*
* [ ] HIPAA mode enabled, `403` understood as the BAA gate — *owner*
* [ ] PHI-adjacent audiences designated — *owner / admin*
* [ ] Retention window set to your policy days — *owner*
* [ ] `GET /settings/hipaa` shape verified, `encryption_algorithm` filed as reporting-only — *compliance officer*
* [ ] PHI access log returning entries — *compliance officer*
* [ ] Compliance-health score compared before/after — *compliance officer*

***

## 4. Boundaries — what this sequence does not do

Three boundaries to keep clear when you report enablement upward, and
when an auditor reads your workspace settings later.

**HIPAA mode is a suite of toggles, not a certification.** Enabling it
activates a set of technical and administrative controls you operate —
encryption at rest, access controls, the PHI audit log, enforced
retention, BAA tracking. Nothing in the enablement certifies your
organization HIPAA-compliant, and the platform does not decide that
your traffic is "compliant." Whether HIPAA applies to you and whether
your configuration satisfies it is yours to answer with your counsel;
the toggle satisfies the *platform-side* precondition for the controls,
not the regulatory one.

**Auditors still want the evidence binder.** The settings above are the
posture; the [evidence binder](/compliance/evidence-binder) is the
export an auditor or a buyer's procurement team reads. Generate the
HIPAA pack from **Settings → Compliance → Binder** after this sequence —
it assembles the PHI access log posture, the BAA status, and your
configured retention into a signed, download-ready pack. An enabled
workspace with no binder export is posture without a handoff.

**The gates you passed stop at the platform edge.** The two hard gates
(403 on enable without a BAA, 422 on PHI send without an executed BAA)
and the campaign precheck are the platform's whole enforcement role.
Minimum-necessary access provisioning, workforce training, patient
consent management, and your own risk assessment sit on your side of
the shared-responsibility table — see
[HIPAA controls — shared responsibility](/compliance/hipaa#shared-responsibility).

## Related pages

* [HIPAA compliance controls](/compliance/hipaa) — the full reference for every surface touched here
* [BAA — Business Associate Agreement flow](/compliance/baa) — the BAA lifecycle this runbook sequences first
* [PHI-adjacent audience designations](/compliance/phi-audiences) — registry endpoint semantics, kept there rather than repeated here
* [Per-domain data retention policy](/compliance/data-retention-policy) — the retention surface beyond the HIPAA window
* [Compliance evidence binder](/compliance/evidence-binder) — the export that hands the posture to an auditor
* [HIPAA onboarding: from BAA to audit-ready](/guides/hipaa-onboarding) — the companion guide covering role/scope restriction and the binder handoff in detail

***

*HIPAA posture is tenant-owned — Orbit provides the controls and the
ledger; the legal determination that PHI is in scope is yours. This page
is not legal advice.*