Skip to main content

​
HIPAA onboarding: from BAA to audit-ready

The HIPAA controls 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 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.

​
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:
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.

​
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. 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 before relying on it.

​
4. Configure data retention

Set the retention window before PHI accumulates beyond it.
  • Dashboard: Settings → Compliance → HIPAA → Data Retention.
  • API:
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 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:
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.
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 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 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