> ## 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.

# Business-Associate-Agreement-(BAA)-Ablauf

> Unterzeichnen Sie Ihre HIPAA Business Associate Agreement mit Devotel: Attestieren Sie den PHI-Umfang, prüfen Sie die Vorlage, signieren Sie mit einer E-Signatur durch Namenseingabe und laden Sie die ausgeführte Kopie herunter.

# Business Associate Agreement (BAA)

Organisationen, die Protected Health Information (PHI) über Devotel Orbit senden, speichern oder verarbeiten, benötigen eine hinterlegte Business Associate Agreement. Die Plattform stellt sicher, dass die BAA-Route vorhanden ist, bevor der HIPAA-Modus aktiviert werden kann: Sobald PHI in den Umfang gelangt, lehnt das sendezeitige Gate den Verkehr mit `HIPAA_BAA_REQUIRED` ab, bis ein ausgeführtes BAA erfasst ist.

Diese Anleitung behandelt den vollständigen Lebenszyklus: die kanonischen `baa_status`-Zustände, wie die sechs `/api/v1/compliance/baa`-Endpunkte zusammenwirken, welche Rolle welchen Endpunkt aufrufen darf, was sich nach der Ausführung eines BAA ändert und wie ein ausgeführtes Agreement auf den Plattform-Standard zurückgesetzt wird.

> Dies ist eine **mandanteneigene HIPAA-Steuerung**: Sie entscheiden, ob PHI im Umfang liegt, führen das Agreement bewusst aus und führen es erneut aus, bevor die jährliche Laufzeit abläuft. Devotel stellt die E-Sign-Pipeline bereit – Vorlagen-Rendering, Erfassung der getippten Signatur, unveränderliche Audit-Verankerung und die gespeicherte ausgeführte PDF –, aber die rechtliche Feststellung, dass PHI im Umfang liegt, liegt bei Ihnen.

***

## Zustände von `baa_status`

Ihre Organisation befindet sich stets in einem von vier Zuständen, die `GET /api/v1/compliance/baa` zurückmeldet:

| Zustand        | Bedeutung                                                                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `not_required` | Die Organisation hat attestiert (oder es ist standardmäßig gesetzt), dass kein PHI im Umfang liegt. Dies ist der Standard für jede neue Organisation.                                          |
| `pending`      | PHI liegt im Umfang (`hipaa_required = true`) und das BAA wartet auf Ausführung. Das Ausführungsformular ist in diesem Zustand verfügbar.                                                      |
| `executed`     | Ein BAA wurde unterzeichnet und liegt innerhalb seiner einjährigen Laufzeit. Dies ist der einzige Zustand, der die HIPAA-Aktivierungs- und PHI-Versand-Gates erfüllt.                          |
| `expired`      | Ein ausgeführtes BAA hat seine einjährige Laufzeit überschritten. PHI-Sendungen werden wieder geblockt, bis Sie erneut ausführen. Eine erneute Ausführung ist ab 60 Tage vor Ablauf verfügbar. |

Die Antwort enthält außerdem die Unterzeichner-Details und den Countdown bis zum Ablauf:

```json theme={null}
{
  "baa_status": "executed",
  "baa_executed_at": "2026-08-10T14:22:31.410Z",
  "baa_template_version": "v1",
  "baa_signer_name": "Jane Roe",
  "baa_signer_email": "jane@example.com",
  "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
  "hipaa_required": true,
  "expires_at": "2027-08-10T14:22:31.410Z",
  "days_until_expiry": 342
}
```

Wenn `hipaa_required` aktiviert wird, während der Status noch `not_required` ist, versetzt der Lesendpunkt die Organisation automatisch nach `pending`, sodass der Ausführungsschritt ohne einen separaten Aufruf geöffnet wird.

***

## Warum der Ablauf mit einer Attestierung beginnt

Der BAA-Ablauf existiert, weil HIPAA für die *Nutzung* gilt, nicht für Konten. Die Plattform nimmt nicht an, dass jeder Workspace PHI verarbeitet – die Organisation attestiert zunächst, dass PHI im Umfang liegt, wodurch das Flag `hipaa_required` gesetzt und der Zustand auf `pending` verschoben wird. Diese Attestierung öffnet den Ausführungsschritt; die Ausführung vollendet dann das Agreement. Diese Reihenfolge schließt eine zirkuläre Abhängigkeit: Der HIPAA-Modus kann ohne ein ausgeführtes BAA nicht aktiviert werden, doch das Dashboard benötigte zugleich einen Weg, das BAA zu *starten*, bevor der HIPAA-Modus existierte.

Sowohl `require` (PHI liegt im Umfang) als auch `decline` (kein PHI im Umfang) schreiben eine `compliance.baa.*`-Audit-Kettenzeile mit dem Akteur – die Attestierung selbst ist damit ein aufgezeichnetes rechtliches Ereignis und kein belangloser Einstellungsschalter.

***

## Der Endpunkt-Ablauf

Alle Routen liegen unter `/api/v1/compliance/baa` und erfordern eine authentifizierte Sitzung. Die sechs nachfolgenden Operationen bilden den vollständigen Lebenszyklus; die Dashboard-Seite **Settings → Compliance → BAA** steuert exakt diese Endpunkte an.

### 1. Aktuellen Zustand lesen

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa" \
  -H "Authorization: Bearer sk_live_..."
```

Jeder `owner` oder `admin` darf lesen. Rufen Sie dies zuerst ab – es zeigt Ihnen, ob die Organisation attestieren, ausführen, erneut ausführen oder herunterladen muss.

### 2. Vorlage einsehen

Prüfen Sie vor der Unterzeichnung den finalen Agreement-Text. `GET /api/v1/compliance/baa/template` liefert die mit dem juristischen Namen Ihrer Organisation bereits ausgefüllte Vorlage. Zur Ausführungszeit gefüllte Felder (Zeitstempel, Dokumentreferenz) erscheinen als lesbare Markierungen statt als rohe Platzhalter, und die Unterzeichnerfelder sind Leerfelder, die das Dashboard während der Eingabe live befüllt.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa/template?version=v1" \
  -H "Authorization: Bearer sk_live_..."
```

Antwort:

```json theme={null}
{
  "version": "v1",
  "covered_entity_name": "Acme Health Ltd",
  "format": "markdown",
  "body": "# Business Associate Agreement\n\nThis Business Associate Agreement..."
}
```

### 3. Attestieren, dass PHI im Umfang liegt

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/require" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "We began sending patient appointment reminders that contain PHI." }'
```

Dies setzt `hipaa_required = true` und verschiebt eine Organisation im Zustand `not_required` nach `pending`. Es öffnet den Ausführungsablauf – es aktiviert den HIPAA-Modus **nicht**. Der optionale `reason` (bis zu 500 Zeichen) wird in der Audit-Zeile erfasst.

### 4. Ausführen mit einer E-Signatur durch Namenseingabe

Die Ausführung ist **owner-only** – eine Click-Wrap-Signatur bindet die Organisation und ist daher keine Aktion auf Developer-Ebene. Der Unterzeichner tippt seinen juristischen Namen erneut in `typed_attestation`, und der Server verlangt eine exakte Übereinstimmung mit `signer_name`; eine Abweichung wird mit `400` abgelehnt, was zugleich automatische Absendungen eines leeren Formulars blockiert.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/execute" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "Jane Roe",
    "signer_email": "jane@example.com",
    "typed_attestation": "Jane Roe"
  }'
```

| Feld                | Regel                                                                           |
| ------------------- | ------------------------------------------------------------------------------- |
| `signer_name`       | Der juristische Name des Unterzeichners (2–200 Zeichen).                        |
| `signer_email`      | Eine gültige E-Mail-Adresse.                                                    |
| `typed_attestation` | Muss **exakt mit** `signer_name` übereinstimmen. Eine Abweichung liefert `400`. |
| `template_version`  | Optional. Standard ist die aktuelle kanonische Version.                         |

Bei Erfolg führt der Server Folgendes aus:

1. Rendert die Vorlage mit den Unterzeichner-Details, den Ausführungszeitstempeln und einer generierten Dokumentreferenz
2. Speichert das gerenderte Dokument als kanonische ausgeführte PDF
3. Kennzeichnet die Organisation als `executed` mit Unterzeichner, Vorlagenversion und Ausführungszeitstempel und erfasst den Ablauf (Ausführung plus die einjährige Standardlaufzeit)
4. Schreibt einen `compliance.baa.executed`-Eintrag in das Audit-Log samt Signaturmethode (`type_the_name`) – der Audit-Eintrag ist der rechtliche Nachweis der Attestierung, und die gespeicherte PDF ist das kanonische Dokument

Die Antwort liefert den neuen Zustand samt Dokumentreferenz:

```json theme={null}
{
  "baa_status": "executed",
  "baa_executed_at": "2026-08-24T09:41:12.008Z",
  "baa_template_version": "v1",
  "baa_signer_name": "Jane Roe",
  "baa_signer_email": "jane@example.com",
  "baa_id": "baa_9f2k…",
  "expires_at": "2027-08-24T09:41:12.008Z",
  "days_until_expiry": 365,
  "hipaa_required": true
}
```

Die Ausführung ist auf wenige Anfragen pro Minute limitiert; sie ist ein bewusster rechtlicher Akt, keine Skriptschleife. (Zur Click-Wrap-Rechtsgrundlage siehe [Voice signatures](/compliance/voice-signatures).)

### 5. Ausgeführte Kopie herunterladen

Sobald ein BAA hinterlegt ist, kann jeder `owner` oder `admin` es abrufen – für Ihre Unterlagen, für das Audit eines Kunden oder für eine Aufsichtsbehörde:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa/download" \
  -H "Authorization: Bearer sk_live_..."
```

Die Antwort enthält eine Download-URL, die **24 Stunden** gültig ist:

```json theme={null}
{
  "url": "https://storage.googleapis.com/…/baa/org_…/baa_….pdf?X-Goog-Signature=…",
  "expires_in_seconds": 86400
}
```

Teilen Sie die URL innerhalb dieses Fensters oder laden Sie die Datei selbst herunter und archivieren Sie sie. Wenn noch kein BAA ausgeführt wurde, liefert der Endpunkt `404`.

### 6. Auf den Plattform-Standard zurücksetzen

Das Zurücksetzen entfernt das hinterlegte Agreement und versetzt die Organisation zurück nach `not_required`. Es ist **owner-only** und nur auf einem ausgeführten oder abgelaufenen BAA aufrufbar – und erst, nachdem der HIPAA-Modus deaktiviert wurde, sodass ein aktiver HIPAA-Workspace nicht still sein eigener Nachweis auflösen kann.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/revert" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Organization no longer processes PHI; returning to default posture." }'
```

Die Audit-Historie und die gespeicherte PDF des ausgeführten BAA bleiben **erhalten** – das Zurücksetzen entfernt den aktiven Zustand, es löscht nicht den Nachweis. Verwenden Sie es, wenn PHI tatsächlich aus dem Umfang herausfällt, oder um einen Workspace auf eine saubere Ausgangslage zurückzusetzen; verwenden Sie stattdessen [decline](#decline-kein-phi-im-umfang-attestieren), wenn sich die „kein PHI"-Attestierung ändert.

### Decline: kein PHI im Umfang attestieren

`POST /api/v1/compliance/baa/decline` (owner oder admin, optionaler `reason`) erfasst, dass PHI nicht im Umfang liegt, und hebt das sendezeitige Gate auf, sobald eine Organisation zuvor eingestiegen war. Es weigert sich, ein hinterlegtes BAA anzufassen – ein Decline kann ein ausgeführtes Agreement nicht zerlegen; dafür ist `revert` da. Da `require` und `decline` symmetrische Attestierungsschalter sind, kann ein Admin, der declined, die Anforderung später wiederherstellen, wenn PHI erneut in den Umfang gelangt.

***

## Rollen und die Audit-Kette

Die Endpunkte für Lesen, Vorschau, Download und Attestierung akzeptieren `owner` oder `admin`. Die beiden Handlungen, die ein Agreement rechtlich binden oder auflösen – `execute` und `revert` – sind nur für `owner`.

| Aktion                                                              | `owner` | `admin` | `developer` / `viewer` / `billing` |
| ------------------------------------------------------------------- | :-----: | :-----: | :--------------------------------: |
| BAA-Zustand lesen                                                   |    Ja   |    Ja   |                Nein                |
| Vorlage einsehen                                                    |    Ja   |    Ja   |                Nein                |
| Ausgeführte Kopie herunterladen                                     |    Ja   |    Ja   |                Nein                |
| PHI im Umfang attestieren (`require`) / nicht im Umfang (`decline`) |    Ja   |    Ja   |                Nein                |
| BAA ausführen                                                       |    Ja   |   Nein  |                Nein                |
| Auf Standard zurücksetzen                                           |    Ja   |   Nein  |                Nein                |

Jeder Schreibvorgang hängt einen `compliance.baa.*`-Eintrag an das Audit-Log der Organisation an – `compliance.baa.hipaa_required` bei require, `compliance.baa.declined` bei decline, `compliance.baa.executed` bei execute, `compliance.baa.reverted` bei revert – jeweils mit Akteur, Grund und (bei der Ausführung) Vorlagenversion und Signaturmethode. Diese Nur-Anhänge-Kette, nicht das aktuelle Statusfeld, ist der rechtliche Nachweis der Attestierung. Sie können sie im Dashboard unter [Settings → Audit log](/guides/audit-log) einsehen.

***

## Was sich nach der Ausführung eines BAA ändert

Die Ausführung des BAA bewirkt zwei Dinge:

1. **Hebt das PHI-Versand-Gate auf.** Solange `hipaa_required` wahr ist und kein laufendes BAA hinterlegt ist, werden ausgehende Sendungen, die PHI berühren, mit `422 HIPAA_BAA_REQUIRED` abgelehnt. Ein ausgeführtes BAA beseitigt diese Ablehnung. (Die Entscheidung des Gates und das Fail-Closed-Verhalten sind unter [Send Gates](/compliance/send-gates#baa-the-hipaa-send-gate) dokumentiert.)
2. **Entsperrt den HIPAA-Modus.** Die Aktivierung des HIPAA-Modus erfordert `baa_status = "executed"`; ein Versuch vor der Ausführung liefert `403`. Sobald der HIPAA-Modus aktiv ist, gelten die in [HIPAA compliance controls](/compliance/hipaa) beschriebenen Steuerungen – PHI-Zugriffsprotokollierung, Datenaufbewahrung und die übrigen – für den Workspace.

Was es **nicht** ändert: Die Ausführung eines BAA aktiviert nicht von sich aus den HIPAA-Modus, bestimmt nicht, ob Ihre Verarbeitung rechtmäßig ist, und ersetzt nicht Ihr eigenes HIPAA-Programm. Das Agreement hält die Pflichten der Plattform Ihnen gegenüber als Business Associate fest; die Feststellung, dass PHI im Umfang liegt, die Bestimmung PHI-naher Zielgruppen und die Konfiguration der Aufbewahrung bleiben mandanteneigen. Wie die Teile zusammenwirken, beschreiben [HIPAA onboarding](/guides/hipaa-onboarding) und [HIPAA compliance controls](/compliance/hipaa).

***

## Dashboard-Ablauf

Derselbe Lebenszyklus ist ohne API-Zugriff unter **Settings → Compliance → BAA** verfügbar:

1. **Statuskarte** – zeigt den aktuellen `baa_status`, das Ausführungsdatum, den Unterzeichner und ein Banner zur erneuten Ausführung, wenn die Laufzeit innerhalb von 60 Tagen abläuft
2. **Vorlagenvorschau** – das gerenderte Agreement mit dem Namen Ihrer Organisation im Ansatz
3. **Attestierungsformular** – Name und E-Mail des Unterzeichners plus das Feld zur Namenseingabe-Signatur, gezeigt für Owner, wenn der Zustand `pending` ist
4. **Download** – ein Link zur ausgeführten Kopie nach der Ausführung, bei jeder Anfrage mit einer frischen 24-Stunden-URL

Wenn PHI noch nicht attestiert wurde, zeigt die Seite eine „PHI-Verarbeitung starten"-Handlungsaufforderung, die die `require`-Attestierung absendet und unmittelbar das Ausführungspaneel öffnet – ganz dem obigen API-Ablauf folgend.

***

## FAQ

**Wie lange gilt ein ausgeführtes BAA?**
Ein Jahr ab Ausführung. Die Zustandsantwort enthält `expires_at` und `days_until_expiry`; innerhalb von 60 Tagen vor Ablauf zeigt das Dashboard ein Banner zur erneuten Ausführung. Nach Ablauf lautet der Status `expired`, und das PHI-Versand-Gate schließt erneut, bis Sie mit demselben Ablauf erneut ausführen.

**Kann ein Admin das BAA ausführen, um Sendungen zu entsperren?**
Nein – Ausführung (und Zurücksetzen) ist owner-only, weil es die Organisation bindet. Ein Admin *kann* PHI als erforderlich oder declined markieren, den Zustand lesen, die Vorlage einsehen und die ausgeführte Kopie herunterladen.

**Was ist der Unterschied zwischen `decline` und `revert`?**
`decline` erfasst, dass kein PHI im Umfang liegt, und hebt das Versand-Gate auf; es weigert sich, ein ausgeführtes BAA anzufassen. `revert` entfernt ein ausgeführtes oder abgelaufenes Agreement vollständig und versetzt die Organisation zurück nach `not_required`, wobei Audit-Historie und gespeicherte PDF erhalten bleiben. Beide hinterlassen Audit-Ketteneinträge.

**Akzeptieren die Endpunkte einen älteren JSONB-Status-Spiegel?**
Der `/api/v1/compliance/baa`-Ablauf ist der kanonische Pfad. Der ältere `PUT /api/v1/settings/hipaa/baa`-Spiegel (dokumentiert unter [HIPAA compliance controls](/compliance/hipaa)) ist nur ein Rückfall für Tenants vor der Migration; sobald eine Organisation einen `baa_status`-Wert hat, lesen die Gates die kanonische Spalte und ignorieren den Spiegel.

***

*Zuletzt aktualisiert: September 2026*
*Bei Fragen zum BAA: [compliance@devotel.io](mailto:compliance@devotel.io)*