Skip to main content

​
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: Die Antwort enthält außerdem die Unterzeichner-Details und den Countdown bis zum Ablauf:
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

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.
Antwort:

​
3. Attestieren, dass PHI im Umfang liegt

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.
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:
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.)

​
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:
Die Antwort enthält eine Download-URL, die 24 Stunden gültig ist:
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.
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, 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. 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 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 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 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 und HIPAA compliance controls.

​
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) 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