HIPAA-Onboarding: vom BAA bis zur Audit-Bereitschaft

Die Referenz HIPAA-Steuerungen erklärt, was jede Steuerung tut. Diese Anleitung ordnet sie in die richtige Reihenfolge — die Sequenz, die einen Gesundheits-Workspace von „wir verarbeiten PHI” zu „wir können einen Audit-Trail vorweisen” führt, ohne am Sende-Gate 422 HIPAA_BAA_REQUIRED zu scheitern — eines der Send-Gates, die die Absender-Compliance vor dem Dispatch einer Nachricht oder eines Anrufs prüfen. Die Reihenfolge ist entscheidend. Der HIPAA-Modus kann vor der Ausführung des BAA nicht aktiviert werden, PHI-Versende werden bis dahin abgelehnt, und Aufbewahrung 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 auf einem Inhaber- oder Admin- Schlüssel. Exportieren Sie ihn, bevor Sie beginnen:

export ORBIT_KEY="dv_live_sk_…"   # live — oder dv_test_sk_… gegen die Sandbox

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

Schlüssel-Präfixe. Sandbox-Schlüssel sind dv_test_sk_…; Live-Schlüssel sind dv_live_sk_…. Jeder Aufruf unten funktioniert auf beiden — die Sandbox liefert dieselben Envelopes, ohne den Live-Compliance-Status zu berühren.
Gemeinsamer Envelope. Jeder Erfolgs-Body ist { "data": { … }, "meta": { "request_id", "timestamp" } }. Fehler sind { "error": { code, message, status }, "meta": … }.

1. Das BAA ausführen

Nichts anderes wird freigeschaltet, bis die Business Associate Agreement (BAA) ausgeführt ist. Zwei Gates lesen den BAA-Status direkt:

Aktivierung des HIPAA-Modus gibt 403 Forbidden zurück, solange der BAA-Status nicht executed ist.
Jeder PHI-Versand wird mit 422 HIPAA_BAA_REQUIRED abgelehnt.

Führen Sie es über den Bereich Compliance → BAA im Dashboard aus, oder steuern Sie dieselben drei Aufrufe über die API. Verwenden Sie für /execute einen Inhaber-Schlüssel (er bindet die Rechtsvereinbarung); ein Inhaber-oder-Admin-Schlüssel genügt für /require und GET /compliance/baa.

1a. Attestieren, dass PHI im Umfang ist

Versetzen Sie die Organisation von not_required nach pending, was den Ausführungsablauf ö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 in der Audit-Zeile aufgezeichnet wird, niemals in einer Spalte.

1b. Mit einer Tipp-ihren-Namen-E-Signatur ausführen

Zeichnen Sie die Attestation auf. typed_attestation muss exakt mit signer_name übereinstimmen — das ist der Schutz gegen eine versehentliche oder leere Formular-Signatur:

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 das BAA ausgeführt ist

Lesen Sie den Lebenszyklus erneut und notieren Sie days_until_expiry — ein ausgeführtes BAA läuft nach seiner einjährigen Laufzeit ab und muss erneut ausgeführt 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); // z. B. 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, der Legacy-Mirror-Hinweis und die vollständigen Anfrageformen sind unter BAA dokumentiert. Für die Konsolen-Übersicht der Ausführung, der jährlichen Neu-Ausführung und der Ablehnungs-/Rücksetz-Steuerungen — plus die Schwester-DPA- und Aufnahme-Einwilligungs-Konsolen — siehe Execute the DPA and BAA, then manage per-call recording consent.

2. Den HIPAA-Modus aktivieren

Mit ausgeführtem BAA schalten Sie das organisations-weite HIPAA-Flag ein. Der HIPAA-Modus ist ein organisations-weites Feature-Flag, das fünf Steuerungen auf einmal aktiviert — Verschlüsselung im Ruhezustand, Zugriffssteuerungen, PHI-Audit-Protokollierung, erzwungene Aufbewahrung und BAA-Verfolgung. Dies ist ein reiner Inhaber-Aufruf.

Dashboard: Einstellungen → 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 einzelner Aufruf — es verschärft die Haltung des Workspace, daher ist keine erneute Authentifizierung erforderlich. Das Deaktivieren ist destruktiv und erfordert eine; dieser Ablauf ist unter Disabling HIPAA Mode dokumentiert. Wenn der BAA-Status nicht executed ist, gibt der Aufruf 403 Forbidden zurück.

3. Rollen und API-Scopes auf das notwendige Minimum einschränken

HIPAAs Minimum-Necessary-Standard ist Ihre Verantwortung — er liegt auf der Kundenseite der Shared-Responsibility-Tabelle. Orbits Steuerungen sind heute grob, also stellen Sie ehrlich dafür bereit:

Verwenden Sie die billing-Rolle für Personal, das nur finanzielle Oberflächen benötigt. Billing-Mitglieder sind auf Abrechnung, Preise und Nutzung beschränkt — sie erhalten 403 auf Endpunkten für Nachrichteninhalte.
Behalten Sie die Need-to-Read aller anderen im Blick: owner, admin, developer und viewer können heute alle Nachrichteninhalte lesen, und jeder Lesevorgang landet im PHI-Zugriffsprotokoll.
Minten Sie API-Schlüssel nur mit den Scopes, die die Integration benötigt, und gewähren Sie messages:read nur Diensten, die tatsächlich PHI-tragende Nachrichteninhalte lesen.

Bekannte Einschränkung: Orbit beschränkt das Lesen von Nachrichteninhalten derzeit nicht auf eine engere Rollengruppe über die Billing-Einschränkung hinaus, und die Nachrichten-Leseendpunkte (GET /messages, GET /messages/{id}) verlangen keinen vom Betreiber angegebenen Begründungscode. Erfüllen Sie den Minimum-Necessary-Standard, indem Sie Workspace-Mitgliedschaft und API-Schlüssel-Scopes so bereitstellen, dass nur Personal, das PHI benötigt, diese Endpunkte erreichen kann. Wenn Ihr Programm eine rollenbezogene Leseeinschränkung für Nachrichteninhalte erfordert, wenden Sie sich vor dem Vertrauen darauf an compliance@devotel.io.

4. Datenaufbewahrung konfigurieren

Legen Sie das Aufbewahrungsfenster fest, bevor sich PHI darüber hinaus ansammelt. data_retention_days akzeptiert 30–3.650; der Standard ist 365.

Dashboard: Einstellungen → Compliance → HIPAA → Datenaufbewahrung.
API (reiner Inhaber-Aufruf, derselbe Endpunkt wie der Schalter):

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 vollständige Status-Objekt (gleiche Form wie der Aktivierungsaufruf oben); prüfen Sie data.data_retention.days. Ein Hintergrundjob sucht nach abgelaufenen Nachrichteninhalten, Anrufaufzeichnungen und Medienanhängen und löscht sie. Audit-Protokolle und PHI-Zugriffsprotokolle werden unabhängig von dieser Richtlinie aufbewahrt — die Löschuhr löscht Ihren Evidenz-Trail nicht. Wenn Sie Anrufe aufzeichnen, pinnen Sie die Voice-Region so, dass sie Ihren Residency-Verpflichtungen entspricht — 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 das Flag und die Aufbewahrung wie beabsichtigt gelandet sind (Inhaber 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 auch ein encryption_algorithm-Feld. Es ist rein berichtend: es spiegelt den Ruhezustands-Verschlüsselungsstandard der Plattform (von Google verwaltetes AES-256 auf Cloud SQL), nicht einen organisations-spezifischen Anwendungsschicht-Cipher. Devotel führt derzeit keine organisations-bezogene Anwendungsschicht-Verschlüsselung von Nachrichtentexten durch, also zitieren Sie dieses Feld gegenüber einem Auditor nicht als Beweis dafür, dass Nachrichtentexte einzeln auf der Anwendungsebene verschlüsselt sind.

6. Das PHI-Zugriffsprotokoll lesen

Sobald der HIPAA-Modus an ist, wird jeder Zugriff auf PHI-haltige Daten in ein Append-only-Audit-Protokoll geschrieben. Jeder Eintrag zeichnet den Benutzer, die Ressource, den Grund (read wird bei Nachrichten-Lesevorgängen automatisch aufgezeichnet) und den Zeitstempel auf. Blättern Sie mit ?limit= und ?cursor= — übergeben Sie die id des letzten gesehenen Eintrags als nächsten cursor (Inhaber 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 Protokoll hält bis zu 10.000 Einträge pro Organisation, wobei die ältesten herausrotieren, ist für owner- und admin-Rollen über das Dashboard oder die API zugänglich und kann für externe Audits exportiert werden. Überprüfen Sie es früh termingebundet — so weisen Sie nach, dass Zugriffe den Rollen- und Scope-Entscheidungen aus Schritt 3 folgen. 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 Procurement-Team eines Käufers Haltung zeigen müssen, generieren Sie das HIPAA-Paket des Evidence Binders aus Einstellungen → Compliance → Binder. Das HIPAA-Framework assembliert PHI-Zugriffsprotokollierung, BAA-Haltung und Ihre konfigurierte Aufbewahrung zu einem signierten, downloadbereiten Paket; jede Generierung wird in Ihrem Audit-Protokoll aufgezeichnet, und der Download-Link verläuft nach 24 Stunden ab.

Healthcare-Aktivierungs-Bundle

Der Compliance-Plugin-Marktplatz liefert ein HIPAA-Healthcare-Aktivierungs-Bundle, das ein Entwurfs-Compliance-Profil, Entwurfs-Kampagnen, einen vertikal-getunten AI-Agenten und eine Opt-in-Flow-Konfiguration in einem Aufruf bereitstellt. Es ist ein Start-Gerüst, kein Ersatz für diese Sequenz: die Bundle-Aktivierung führt das BAA nie aus, aktiviert nie den HIPAA-Modus und platziert nie einen Versand. Führen Sie zuerst die Schritte 1–6 oben aus, dann aktivieren Sie das Bundle und arbeiten Sie dessen Go-Live-Checkliste vom Entwurf zur Produktion ab.

Reihenfolge-Checkliste

BAA ausgeführt und baa_status als executed bestätigt — Inhaber-Rolle
HIPAA-Modus über den Schalter oder PUT /settings/hipaa aktiviert — Inhaber-Rolle
Mitgliedschaft auf das notwendige Minimum zugeschnitten; messages:read nur auf Schlüssel gescoped, die es benötigen — Administrator
data_retention_days auf Ihr Richtlinienfenster gesetzt — Administrator
Voice-Region gepinnt, falls Ihre Residency-Verpflichtungen einschränken, wo aufgezeichnete Audio liegen darf — Administrator
GET /settings/hipaa verifiziert, mit encryption_algorithm als rein berichtend behandelt — Compliance-Beauftragter
PHI-Zugriffsprotokoll termingebundene überprüft — Compliance-Beauftragter
HIPAA-Evidence-Binder generiert und über den 24-Stunden-Link übergeben — Compliance-Beauftragter

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

HIPAA-Onboarding: vom BAA bis zur Audit-Bereitschaft

HIPAA-Onboarding: vom BAA bis zur Audit-Bereitschaft

1. Das BAA ausführen

1a. Attestieren, dass PHI im Umfang ist

1b. Mit einer Tipp-ihren-Namen-E-Signatur ausführen

1c. Bestätigen, dass das BAA ausgeführt ist

2. Den HIPAA-Modus aktivieren

3. Rollen und API-Scopes auf das notwendige Minimum einschränken

4. Datenaufbewahrung konfigurieren

5. Die Konfiguration verifizieren

6. Das PHI-Zugriffsprotokoll lesen

7. Den HIPAA-Evidence-Binder exportieren

Healthcare-Aktivierungs-Bundle

Reihenfolge-Checkliste

​HIPAA-Onboarding: vom BAA bis zur Audit-Bereitschaft

​1. Das BAA ausführen

​1a. Attestieren, dass PHI im Umfang ist

​1b. Mit einer Tipp-ihren-Namen-E-Signatur ausführen

​1c. Bestätigen, dass das BAA ausgeführt ist

​2. Den HIPAA-Modus aktivieren

​3. Rollen und API-Scopes auf das notwendige Minimum einschränken

​4. Datenaufbewahrung konfigurieren

​5. Die Konfiguration verifizieren

​6. Das PHI-Zugriffsprotokoll lesen

​7. Den HIPAA-Evidence-Binder exportieren

​Healthcare-Aktivierungs-Bundle

​Reihenfolge-Checkliste

HIPAA-Onboarding: vom BAA bis zur Audit-Bereitschaft

1. Das BAA ausführen

1a. Attestieren, dass PHI im Umfang ist

1b. Mit einer Tipp-ihren-Namen-E-Signatur ausführen

1c. Bestätigen, dass das BAA ausgeführt ist

2. Den HIPAA-Modus aktivieren

3. Rollen und API-Scopes auf das notwendige Minimum einschränken

4. Datenaufbewahrung konfigurieren

5. Die Konfiguration verifizieren

6. Das PHI-Zugriffsprotokoll lesen

7. Den HIPAA-Evidence-Binder exportieren

Healthcare-Aktivierungs-Bundle

Reihenfolge-Checkliste