Skip to main content

​
HIPAA mode first enablement — operator runbook

The HIPAA controls reference describes every HIPAA surface in detail, and the 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 (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.)
  • 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.
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’s subject — this runbook only fixes where they sit in the sequence.

​
Step 2 — Enable HIPAA mode

Owner-only, and gated on step 1:
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.

​
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.
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 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:
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 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 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:
    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.)
  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:
    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 page; the alerting thresholds that watch the score continuously are in the 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 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.
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.