> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Führen Sie einen Gesundheits-Workspace vom unterzeichneten BAA bis zur PHI-Audit-Bereitschaft — HIPAA-Modus aktivieren, Rollen und API-Scopes einschränken, Aufbewahrung festlegen, das PHI-Zugriffsprotokoll lesen und den Evidence Binder exportieren.

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

Die Referenz [HIPAA-Steuerungen](/compliance/hipaa) 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](/compliance/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:

```bash theme={null}
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:

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```typescript Node.js theme={null}
  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"
  ```
</CodeGroup>

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript Node.js theme={null}
  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"
  ```
</CodeGroup>

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.orbit.devotel.io/api/v1/compliance/baa \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  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
  ```
</CodeGroup>

```json theme={null}
{
  "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](/compliance/hipaa#5-business-associate-agreement-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](/guides/compliance-dpa-baa-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:**

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

  ```typescript Node.js theme={null}
  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
  ```
</CodeGroup>

```json theme={null}
{
  "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](/compliance/hipaa#6-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](/compliance/hipaa#shared-responsibility). 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](mailto: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):

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

  ```typescript Node.js theme={null}
  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
  ```
</CodeGroup>

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](/compliance/voice-data-residency) 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):

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.orbit.devotel.io/api/v1/settings/hipaa \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  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);
  ```
</CodeGroup>

```json theme={null}
{
  "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):

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50" \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  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);
  ```
</CodeGroup>

```json theme={null}
{
  "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](/compliance/evidence-binder) 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](/compliance/plugin-marketplace) 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*