HIPAA onboarding: from BAA to audit-ready

The HIPAA controls reference explains what each control does. This guide is the canonical end-to-end walkthrough that 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. The first-enablement runbook is the checklist-only companion that hands the same sequence to operations without repeating the samples here. 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. Every step below runs against https://api.orbit.devotel.io/api/v1 with an X-API-Key header on an owner or admin key. Export it before you start:

export ORBIT_KEY="dv_live_sk_…"   # live — or dv_test_sk_… against the sandbox

Two conventions hold for every response on this page:

Key prefixes. Sandbox keys are dv_test_sk_…; live keys are dv_live_sk_…. Every call below works on either — sandbox returns the same envelopes without touching live compliance state.
Shared envelope. Every success body is { "data": { … }, "meta": { "request_id", "timestamp" } }. Errors are { "error": { code, message, status }, "meta": … }.

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 drive the same three calls through the API. Use an owner key for /execute (it binds the legal agreement); an owner-or-admin key is enough for /require and GET /compliance/baa.

1a. Attest that PHI is in scope

Move the organization from not_required to pending, which opens the execute flow:

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" }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/compliance/baa/require",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reason: "Clinic messaging will carry PHI" }),
  },
);
console.log((await res.json()).data.baa_status); // "pending"

{
  "data": {
    "baa_status": "pending",
    "baa_executed_at": null,
    "baa_template_version": null,
    "baa_signer_name": null,
    "baa_signer_email": null,
    "baa_pdf_gcs_url": null,
    "hipaa_required": true,
    "expires_at": null,
    "days_until_expiry": null
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

reason is optional free text recorded on the audit row, never on a column.

1b. Execute with a type-the-name e-signature

Record the attestation. typed_attestation must match signer_name exactly — it is the defence against an accidental or blank-form sign:

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"
  }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/compliance/baa/execute",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      signer_name: "Ada Lovelace",
      signer_email: "ada@clinic.example",
      typed_attestation: "Ada Lovelace",
    }),
  },
);
console.log((await res.json()).data.baa_status); // "executed"

{
  "data": {
    "baa_status": "executed",
    "baa_executed_at": "2026-09-23T14:02:11.482Z",
    "baa_template_version": "v1",
    "baa_signer_name": "Ada Lovelace",
    "baa_signer_email": "ada@clinic.example",
    "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
    "hipaa_required": true,
    "expires_at": "2027-09-23T14:02:11.482Z",
    "days_until_expiry": 365,
    "baa_id": "baa_…"
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

1c. Confirm the BAA is executed

Re-read the lifecycle and note days_until_expiry — an executed BAA expires after its one-year term and must be re-executed:

curl https://api.orbit.devotel.io/api/v1/compliance/baa \
  -H "X-API-Key: $ORBIT_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/compliance/baa",
  { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
);
console.log((await res.json()).data.days_until_expiry); // e.g. 365

{
  "data": {
    "baa_status": "executed",
    "baa_executed_at": "2026-09-23T14:02:11.482Z",
    "baa_template_version": "v1",
    "baa_signer_name": "Ada Lovelace",
    "baa_signer_email": "ada@clinic.example",
    "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
    "hipaa_required": true,
    "expires_at": "2027-09-23T14:02:11.482Z",
    "days_until_expiry": 365
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

The BAA lifecycle, the legacy-mirror caveat, and the full request shapes are documented under BAA. For the console walkthrough of execution, annual re-execution, and the decline/revert controls — plus the sibling DPA and recording-consent consoles — see Execute the DPA and BAA, then manage per-call recording consent.

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. This is an owner-only call.

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

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 }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa",
  {
    method: "PUT",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  },
);
console.log((await res.json()).data.enabled); // true

{
  "data": {
    "enabled": true,
    "enabled_at": "2026-09-23T14:05:40.118Z",
    "last_enabled_at": "2026-09-23T14:05:40.118Z",
    "disabled_at": null,
    "enable_history": [
      { "enabledAt": "2026-09-23T14:05:40.118Z" }
    ],
    "baa_status": "executed",
    "hipaa_required": true,
    "baa": {
      "signed": true,
      "signedAt": "2026-09-23T14:02:11.482Z",
      "documentPresent": true,
      "history": []
    },
    "data_retention": { "enabled": true, "days": 365 },
    "encryption_algorithm": "AES-256-GCM",
    "phi_access_log_count": 0
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

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. If BAA status is not executed, the call returns 403 Forbidden.

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 support@orbit.devotel.io before relying on it.

4. Configure data retention

Set the retention window before PHI accumulates beyond it. data_retention_days accepts 30–3,650; the default is 365.

Dashboard: Settings → Compliance → HIPAA → Data Retention.
API (owner-only, same endpoint as the toggle):

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 }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa",
  {
    method: "PUT",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true, data_retention_days: 90 }),
  },
);
console.log((await res.json()).data.data_retention.days); // 90

The response echoes the full status object (same shape as the enable call above); check data.data_retention.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 (owner or admin):

curl https://api.orbit.devotel.io/api/v1/settings/hipaa \
  -H "X-API-Key: $ORBIT_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa",
  { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
);
const { data } = await res.json();
console.log(data.enabled, data.data_retention.days);

{
  "data": {
    "enabled": true,
    "enabled_at": "2026-09-23T14:05:40.118Z",
    "last_enabled_at": "2026-09-23T14:05:40.118Z",
    "disabled_at": null,
    "enable_history": [ { "enabledAt": "2026-09-23T14:05:40.118Z" } ],
    "baa_status": "executed",
    "hipaa_required": true,
    "baa": { "signed": true, "signedAt": "2026-09-23T14:02:11.482Z", "documentPresent": true, "history": [] },
    "data_retention": { "enabled": true, "days": 90 },
    "encryption_algorithm": "AES-256-GCM",
    "phi_access_log_count": 12
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

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. Page through it with ?limit= and ?cursor= — pass the id of the last entry you saw as the next cursor (owner or admin):

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

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50",
  { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
);
const { data } = await res.json();
console.log(data.entries[0]?.resource, data.has_more);

{
  "data": {
    "entries": [
      {
        "id": "phi_…",
        "userId": "user_…",
        "resource": "message:msg_…",
        "reason": "read",
        "accessedAt": "2026-09-23T14:12:07.901Z"
      },
      {
        "id": "phi_…",
        "userId": "user_…",
        "resource": "contact:con_…",
        "reason": "treatment",
        "accessedAt": "2026-09-23T13:58:44.210Z"
      }
    ],
    "has_more": true,
    "total": 12
  },
  "meta": { "request_id": "…", "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. When has_more is true, send the last entry’s id as ?cursor= to fetch the next page.

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

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

HIPAA onboarding: from BAA to audit-ready

HIPAA onboarding: from BAA to audit-ready

1. Execute the BAA

1a. Attest that PHI is in scope

1b. Execute with a type-the-name e-signature

1c. Confirm the BAA is executed

2. Enable HIPAA mode

3. Restrict roles and API scopes to minimum necessary

4. Configure data retention

5. Verify the configuration

6. Read the PHI access log

7. Export the HIPAA evidence binder

Healthcare activation bundle

Order-of-operations checklist

​HIPAA onboarding: from BAA to audit-ready

​1. Execute the BAA

​1a. Attest that PHI is in scope

​1b. Execute with a type-the-name e-signature

​1c. Confirm the BAA is executed

​2. Enable HIPAA mode

​3. Restrict roles and API scopes to minimum necessary

​4. Configure data retention

​5. Verify the configuration

​6. Read the PHI access log

​7. Export the HIPAA evidence binder

​Healthcare activation bundle

​Order-of-operations checklist

HIPAA onboarding: from BAA to audit-ready

1. Execute the BAA

1a. Attest that PHI is in scope

1b. Execute with a type-the-name e-signature

1c. Confirm the BAA is executed

2. Enable HIPAA mode

3. Restrict roles and API scopes to minimum necessary

4. Configure data retention

5. Verify the configuration

6. Read the PHI access log

7. Export the HIPAA evidence binder

Healthcare activation bundle

Order-of-operations checklist