HIPAA-Onboarding: von der BAA zur Audit-Bereitschaft

Die HIPAA controls-Referenz erklärt, was jede Kontrolle tut. Dieser Guide ist der kanonische End-zu-End-Durchgang, der sie in Reihenfolge bringt — die Sequenz, die einen Healthcare-Workspace von “wir verarbeiten PHI” zu “wir können einen Audit-Trail vorzeigen” bringt, ohne das 422 HIPAA_BAA_REQUIRED-Sende-Gate auszulösen. Das First-Enablement-Runbook ist der Checklisten-begleiter, der dieselbe Sequenz ohne die Beispiele hier an Operations übergibt. Die Reihenfolge zählt. Der HIPAA-Modus kann nicht aktiviert werden, bevor die BAA vollzogen ist, PHI-Sendungen werden abgelehnt, bis sie es ist, und Retention schützt Daten erst, sobald sie konfiguriert ist. Folgen Sie den Schritten von oben nach unten. Jeder Schritt unten läuft gegen https://api.orbit.devotel.io/api/v1 mit einem X-API-Key-Header unter einem owner- oder admin-Key. Exportieren Sie ihn, bevor Sie beginnen:

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

Zwei Konventionen gelten für jede Antwort auf dieser Seite:

Key-Präfixe. Sandbox-Keys sind dv_test_sk_…; Live-Keys sind dv_live_sk_…. Jeder Aufruf unten funktioniert auf beiden — die Sandbox liefert dieselben Envelopes, ohne Live-Compliance-Zustand anzufassen.
Geteilter Envelope. Jeder Erfolgs-Body ist { "data": { … }, "meta": { "request_id", "timestamp" } }. Fehler sind { "error": { code, message, status }, "meta": … }.

1. Die BAA vollziehen

Nichts anderes gibt den Weg frei, bis das Business Associate Agreement (BAA) vollzogen ist. Zwei Gates lesen den BAA-Status direkt:

Den HIPAA-Modus aktivieren liefert 403 Forbidden, solange der BAA-Status nicht executed ist.
Jede PHI-Sendung wird mit 422 HIPAA_BAA_REQUIRED abgelehnt.

Vollziehen Sie sie über das Paneel Compliance → BAA im Dashboard oder fahren Sie dieselben drei Aufrufe über die API. Nutzen Sie einen owner-Key für /execute (er bindet die rechtliche Vereinbarung); ein owner-oder-admin-Key genügt für /require und GET /compliance/baa.

1a. Bestätigen, dass PHI im Scope ist

Bewegen Sie die Organisation von not_required nach pending, was den Execute-Fluss öffnet:

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 ist optionaler Freitext, der auf der Audit-Zeile erfasst wird, nie auf einer Spalte.

1b. Mit einer Name-eintippen-E-Signatur vollziehen

Zeichnen Sie die Attestierung auf. typed_attestation muss signer_name exakt entsprechen — das ist die Verteidigung gegen ein versehentliches oder Leerformular-Signieren:

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. Bestätigen, dass die BAA vollzogen ist

Lesen Sie den Lebenszyklus erneut und notieren Sie days_until_expiry — eine vollzogene BAA läuft nach ihrer Einjahresfrist ab und muss neu vollzogen werden:

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": "…" }
}

Der BAA-Lebenszyklus, die Legacy-Mirror-Einschränkung und die vollen Request-Formen sind unter BAA dokumentiert. Für den Konsolen-Durchgang der Vollziehung, der jährlichen Neubestätigung und der Decline-/Revert-Kontrollen — plus der benachbarten DPA- und Recording-Consent-Konsolen — siehe Execute the DPA and BAA, then manage per-call recording consent.

2. Den HIPAA-Modus aktivieren

Mit vollzogener BAA schalten Sie die HIPAA-Flagge je Organisation ein. Der HIPAA-Modus ist ein Feature-Flag je Organisation, das fünf Kontrollen auf einmal aktiviert — Verschlüsselung ruhender Daten, Zugriffskontrollen, PHI-Audit-Logging, erzwungene Retention und BAA-Nachverfolgung. Dies ist ein owner-only-Aufruf.

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": "…" }
}

Das Aktivieren ist ein einziger Aufruf — es verschärft die Haltung des Workspace, daher ist keine Re-Authentifizierungs-Challenge erforderlich. Das Deaktivieren ist destruktiv und verlangt eine; jener Fluss ist unter Disabling HIPAA Mode dokumentiert. Ist der BAA-Status nicht executed, liefert der Aufruf 403 Forbidden.

3. Rollen und API-Scopes auf das nötige Minimum beschränken

HIPAas Minimum-Necessary-Standard liegt in Ihrer Verantwortung — er sitzt auf der Kundenseite der Shared-Responsibility-Tabelle. Orbits Kontrollen sind heute grobkörnig, also provisionieren Sie ehrlich dafür:

Nutzen Sie die billing-Rolle für Mitarbeitende, die nur finanzielle Oberflächen brauchen. Billing-Mitglieder sind auf Billing, Preise und Usage beschränkt — sie erhalten 403 auf Endpunkte mit Nachrichteninhalt.
Behalten Sie das Lese-Bedürfnis aller anderen im Blick: owner, admin, developer und viewer können heute alle Nachrichteninhalt lesen, und jeder Lesezugriff landet im PHI-Zugriffslog.
Prägen Sie API-Keys mit nur den Scopes, die die Integration braucht, und gewähren Sie messages:read nur Services, die wirklich PHI-tragenden Nachrichteninhalt lesen.

Bekannte Einschränkung: Orbit beschränkt Lesezugriffe auf Nachrichteninhalt heute nicht auf eine engere Rollenmenge über die Billing-Beschränkung hinaus, und die Nachrichten-Lese-Endpunkte (GET /messages, GET /messages/{id}) verlangen keinen vom Betreiber gelieferten Reason-Code. Erfüllen Sie den Minimum-Necessary-Standard, indem Sie Workspace-Mitgliedschaft und API-Key-Scopes so provisionieren, dass nur Personal, das PHI braucht, jene Endpunkte erreicht. Wenn Ihr Programm eine rollenbasierte Lesebeschränkung auf Nachrichteninhalt verlangt, kontaktieren Sie support@orbit.devotel.io, bevor Sie sich darauf verlassen.

4. Daten-Retention konfigurieren

Setzen Sie das Retention-Fenster, bevor sich PHI darüber hinaus ansammelt. data_retention_days akzeptiert 30–3.650; der Default ist 365.

Dashboard: Settings → Compliance → HIPAA → Data Retention.
API (owner-only, derselbe Endpunkt wie der 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

Die Antwort spiegelt das volle Statusobjekt (dieselbe Form wie der Aktivierungsaufruf oben); prüfen Sie data.data_retention.days. Ein Hintergrund-Job sucht nach abgelaufenem Nachrichteninhalt, Anrufaufzeichnungen und Medien-Anhängen und löscht sie. Audit-Logs und PHI-Zugriffslogs werden unabhängig von dieser Policy aufbewahrt — die Löschungsuhr löscht Ihre Beweisspur nicht. Wenn Sie Anrufe aufzeichnen, pinnen Sie gleichzeitig die Sprach-Region, um Ihre Residency-Pflichten zu erfüllen — siehe Voice Data Residency & Retention für den Residency-Regler, der Aufzeichnungen, Voicemail und Live-Medien in einer Region hält.

5. Die Konfiguration verifizieren

Bestätigen Sie, dass Flagge und Retention so gelandet sind, wie Sie es beabsichtigt haben (owner oder 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": "…" }
}

Prüfen Sie enabled und data_retention.days in der Antwort.

Die Antwort trägt außerdem ein Feld encryption_algorithm. Es ist nur Reporting: es spiegelt den Plattform-Standard für Verschlüsselung ruhender Daten (von Google verwaltetes AES-256 auf Cloud SQL), keine anwendungsschichtige Chiffre je Organisation. Devotel führt gegenwärtig keine anwendungsschichtige Verschlüsselung von Nachrichten-Bodies je Organisation durch, also zitieren Sie dieses Feld einem Auditor nicht als Beleg, dass Nachrichten-Bodies auf Anwendungsschicht einzeln verschlüsselt sind.

6. Das PHI-Zugriffslog lesen

Sobald der HIPAA-Modus an ist, wird jeder Zugriff auf PHI-haltige Daten in ein Append-only-Audit-Log geschrieben. Jeder Eintrag zeichnet den Nutzer, die Ressource, den Grund (read wird bei Nachrichten-Lesezugriffen automatisch erfasst) und den Zeitstempel auf. Blättern Sie mit ?limit= und ?cursor= — übergeben Sie die id des letzten gesehenen Eintrags als nächsten cursor (owner oder 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": "…" }
}

Das Log hält bis zu 10.000 Einträge je Organisation, wobei die ältesten hinausrotiert werden, ist den Rollen owner und admin über Dashboard oder API zugänglich und kann für externe Audits exportiert werden. Prüfen Sie es früh nach einem Plan — so weisen Sie nach, dass der Zugriff den Rollen- und Scope-Entscheidungen aus Schritt 3 folgt. Wenn has_more true ist, senden Sie die id des letzten Eintrags als ?cursor=, um die nächste Seite zu holen.

7. Den HIPAA-Evidence-Binder exportieren

Wenn Sie einem Auditor oder dem Beschaffungsteam eines Käufers Ihre Haltung zeigen müssen, erzeugen Sie das HIPAA-Paket des Evidence-Binders über Settings → Compliance → Binder. Das HIPAA-Framework fügt PHI-Zugriffslogging, BAA-Haltung und Ihre konfigurierte Retention zu einem signierten, download-bereiten Paket zusammen; jede Erzeugung wird in Ihrem Audit-Log erfasst, und der Download-Link läuft nach 24 Stunden ab.

Healthcare-Aktivierungsbundle

Der Compliance-Plugin-Marktplatz liefert ein HIPAA healthcare-Aktivierungsbundle, das mit einem Aufruf ein Compliance-Profil im Entwurf, Entwurfs-Kampagnen, einen auf die Branche abgestimmten KI-Agenten und eine Opt-in-Fluss-Konfiguration anlegt. Es ist ein Startgerüst, kein Ersatz für diese Sequenz: Das Bundle zu aktivieren vollzieht nie die BAA, aktiviert nie den HIPAA-Modus und setzt nie eine Sendung ab. Fahren Sie zuerst die Schritte 1–6 oben, aktivieren Sie dann das Bundle und arbeiten Sie dessen Go-Live-Checkliste vom Entwurf zur Produktion durch.

Reihenfolge-Checkliste

BAA vollzogen und baa_status als executed bestätigt — owner-Rolle
HIPAA-Modus über den Toggle oder PUT /settings/hipaa aktiviert — owner-Rolle
Mitgliedschaft auf das nötige Minimum beschnitten; messages:read nur auf Keys gescoped, die es brauchen — administrator
data_retention_days auf Ihr Policy-Fenster gesetzt — administrator
Sprach-Region gepinnt, falls Ihre Residency-Pflichten beschränken, wo aufgezeichnetes Audio leben darf — administrator
GET /settings/hipaa verifiziert, mit encryption_algorithm als nur Reporting behandelt — compliance officer
PHI-Zugriffslog nach Plan geprüft — compliance officer
HIPAA-Evidence-Binder erzeugt und über den 24-Stunden-Link übergeben — compliance officer

WhatsApp

Developer console

Contact center

Guides

Admin

Messaging Controls

Audience & Support Tools

HIPAA-Onboarding: von der BAA zur Audit-Bereitschaft

HIPAA-Onboarding: von der BAA zur Audit-Bereitschaft

1. Die BAA vollziehen

1a. Bestätigen, dass PHI im Scope ist

1b. Mit einer Name-eintippen-E-Signatur vollziehen

1c. Bestätigen, dass die BAA vollzogen ist

2. Den HIPAA-Modus aktivieren

3. Rollen und API-Scopes auf das nötige Minimum beschränken

4. Daten-Retention konfigurieren

5. Die Konfiguration verifizieren

6. Das PHI-Zugriffslog lesen

7. Den HIPAA-Evidence-Binder exportieren

Healthcare-Aktivierungsbundle

Reihenfolge-Checkliste

​HIPAA-Onboarding: von der BAA zur Audit-Bereitschaft

​1. Die BAA vollziehen

​1a. Bestätigen, dass PHI im Scope ist

​1b. Mit einer Name-eintippen-E-Signatur vollziehen

​1c. Bestätigen, dass die BAA vollzogen ist

​2. Den HIPAA-Modus aktivieren

​3. Rollen und API-Scopes auf das nötige Minimum beschränken

​4. Daten-Retention konfigurieren

​5. Die Konfiguration verifizieren

​6. Das PHI-Zugriffslog lesen

​7. Den HIPAA-Evidence-Binder exportieren

​Healthcare-Aktivierungsbundle

​Reihenfolge-Checkliste

HIPAA-Onboarding: von der BAA zur Audit-Bereitschaft

1. Die BAA vollziehen

1a. Bestätigen, dass PHI im Scope ist

1b. Mit einer Name-eintippen-E-Signatur vollziehen

1c. Bestätigen, dass die BAA vollzogen ist

2. Den HIPAA-Modus aktivieren

3. Rollen und API-Scopes auf das nötige Minimum beschränken

4. Daten-Retention konfigurieren

5. Die Konfiguration verifizieren

6. Das PHI-Zugriffslog lesen

7. Den HIPAA-Evidence-Binder exportieren

Healthcare-Aktivierungsbundle

Reihenfolge-Checkliste