> ## 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: BAA'dan audit'e hazır

> Sağlık workspace'ini BAA imzasından PHI audit hazırlığına götüren sıra — HIPAA modunu etkinleştir, rol ve API scope'larını kısıtla, saklamayı yapılandır, PHI erişim logunu oku ve delil paketini dışa aktar.

# HIPAA onboarding: BAA'dan audit'e hazır

[HIPAA kontrolleri](/compliance/hipaa) referansı her kontrolün ne yaptığını açıklar. Bu rehber onları sıraya koyar — bir sağlık workspace'ini "PHI işliyoruz"dan "audit izini gösterebiliriz"e götüren sıra — `422 HIPAA_BAA_REQUIRED` send gate'ine takılmadan — bir mesaj veya çağrı göndermeden önce gönderici uyumluluğunu kontrol eden [send gate'ler](/compliance/send-gates)den biri.

Sıra önemli. HIPAA modu BAA yürütülmeden etkinleştirilemez, PHI gönderimleri o zamana kadar reddedilir ve saklama ancak yapılandırıldığında verileri korur. Adımları yukarıdan aşağıya izleyin.

Aşağıdaki her adım `https://api.orbit.devotel.io/api/v1` adresine bir `X-API-Key` başlığı ile bir **sahip veya admin** anahtarında çalışır. Başlamadan önce dışa aktarın:

```bash theme={null}
export ORBIT_KEY="dv_live_sk_…"   # live — veya sandbox'ta dv_test_sk_…
```

Bu sayfadaki her yanıt için iki sözleşme geçerlidir:

* **Anahtar önekler.** Sandbox anahtarları `dv_test_sk_…`; live anahtarları `dv_live_sk_…`. Aşağıdaki her çağrı her ikisinde de çalışır — sandbox aynı zarfı canlı uyumluluk durumuna dokunmadan döndürür.
* **Paylaşılan zarf.** Her başarı body'si `{ "data": { … }, "meta": { "request_id", "timestamp" } }` şeklindedir. Hatalar `{ "error": { code, message, status }, "meta": … }` şeklindedir.

## 1. BAA'yı yürütün

Business Associate Agreement (BAA) yürütülene kadar başka hiçbir şey açılmaz. İki gate BAA durumunu doğrudan okur:

* **HIPAA modunu etkinleştirme**, BAA durumu `executed` olmadığı sürece `403 Forbidden` döndürür.
* **Her PHI gönderimi** `422 HIPAA_BAA_REQUIRED` ile reddedilir.

Dashboard'daki **Compliance → BAA** bölmesinden üzerinden yürütün, ya da aynı üç çağrıyı API üzerinden yönlendirin. `/execute` için sahip anahtarı kullanın (yasal anlaşmayı bağlar); `/require` ve `GET /compliance/baa` için sahip-veya-admin anahtarı yeterlidir.

### 1a. PHI'nın kapsamda olduğunu attest edin

Organizasyonu `not_required`'dan `pending`'e taşıyın, bu yürütme akışını açar:

<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`, hiçbir zaman bir sütun üzerinde değil, audit satırına yazılan isteğe bağlı serbest metindir.

### 1b. İsmini yaz-e-imza ile yürütün

Attestation'ı kaydedin. `typed_attestation`, `signer_name` ile tam eşleşmelidir — bu, yanlışlıkla veya boş form imzasında savunmadır:

<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. BAA'nın yürütüldüğünü onaylayın

Yaşam döngüsünü yeniden okuyun ve `days_until_expiry`'yi not alın — yürütülen bir BAA bir yıllık terim süresi sonunda sona erer ve yeniden yürütülmelidir:

<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); // ör. 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": "…" }
}
```

BAA yaşam döngüsü, eski-ayna uyarısı ve tam istek şekilleri [BAA](/compliance/hipaa#5-business-associate-agreement-baa) altında belgelenir. Yürütme, yıllık yeniden yürütme ve reddet/geri al kontrollerinin konsol turu — artı kardeş DPA ve kayıt izni konsolları — için bkz. [DPA ve BAA'yı yürüt, sonra çağrı-başı-kayıt-izni'ni yönet](/guides/compliance-dpa-baa-recording-consent).

## 2. HIPAA modunu etkinleştirin

BAA yürütüldükten sonra organizasyon-başı HIPAA bayrağını açın. HIPAA modu, beş kontrolu bir arada etkinleştiren organizasyon-başı bir özellik bayrağıdır — bekleyen veri şifreleme, erişim kontrolleri, PHI audit loglama, zorlanmış saklama ve BAA takibi. Bu sahibine özel bir çağrıdır.

* **Dashboard:** **Ayarlar → Compliance → HIPAA Modu Geçişi**.
* **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": "…" }
}
```

Alma tek bir çağrıdır — workspace'in duruşunu sıkılaştır, bu yüzden yeniden kimlik doğrulama gerekmez. Devre dışı bırakma yıkıcıdır ve bir tanesini gerektirir; bu akış [HIPAA Modunu Devre Dışı Bırakma](/compliance/hipaa#6-disabling-hipaa-mode) altında belgelenir. BAA durumu `executed` değilse, çağrı `403 Forbidden` döndürür.

## 3. Rolleri ve API kapsamlarını asgari gerekilere kısıtlayın

HIPAA'nın *asgari gerekli* standardı **sizin** sorumluluğunuz — [paylaşılan sorumluluk tablosunun](/compliance/hipaa#shared-responsibility) müşteri tarafında durur. Orbit'in kontrolleri bugün kaba, bu yüzden dürüstçe provision edin:

* Sadece mali yüzeylere ihtitraç eden personel için **`billing` rolünü** kullanın. Billing üyeleri faturalama, fiyatlandırma ve kullanımla sınırlı — mesaj-içerik endpoint'lerinde `403` alırlar.
* Diğer herkesin okuma ihtiyacını aklında tutun: `owner`, `admin`, `developer` ve `viewer` bugün mesaj içeriğini okuyabilir, ve her okuma PHI erişim log'una iner.
* API anahtarlarını sadece entegrasyonun ihtiyaç duyduğu kapsamlarla çıkarın ve `messages:read`'yi sadece gerçekten PHI taşıyan mesaj içeriği okuyan servislere verin.

> **Bilinen sınırlama:** Orbit şu anda mesaj-içerik okumalarını billing sınırlamasının ötesinde daha dar bir rol setine kısıtlamıyor, ve mesaj okuma endpoint'leri (`GET /messages`, `GET /messages/{id}`) operatör-tarafından-verilen neden kodu gerektirmiyor. Asgari-gerekli standardını workspace üyeliği ve API-anahtar kapsamlarını sadece PHI'ye ihtitraç eden personelin bu endpoint'lere ulaşabileceği şekilde provision ederek karşılayın. Programınız mesaj içeriği üzerinde rol-başı okuma kısıtlaması gerektiriyorsa, buna güvenmeden önce [compliance@devotel.io](mailto:compliance@devotel.io)'ya başvurun.

## 4. Veri saklamayı yapılandırın

PHI ötesinde biriktirmeden önce saklama penceresini ayarlayın. `data_retention_days` 30–3.650 kabul eder; varsayılan 365'tir.

* **Dashboard:** **Ayarlar → Compliance → HIPAA → Veri Saklama**.
* **API** (sahibine özel, toggle ile aynı endpoint):

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

Yanıt tam durum nesnesini yansıtır (yukarıdaki etkinleştirme çağrısı ile aynı şekil); `data.data_retention.days`'yi kontrol edin.

Bir arka plan işi süresi dolan mesaj içeriği, çağrı kayıtları ve media eklentilerini tarar ve siler. Audit log'ları ve PHI erişim log'ları bu politikadan bağımsız saklanır — silme saati delil izinizi silmez.

Çağrı kaydediyorsanız, ses bölgesini aynı zamanda yasal ikamet yükümlülüklerinizle eşleşecek şekilde sabitleyin — bkz. [Ses Veri İkamet ve Saklama](/compliance/voice-data-residency) için kayıtları, mesaj kutusu ve canlı media'yı bir bölgede tutan ikamet düğmesi.

## 5. Yapılandırmayı doğrulayın

Bayrağın ve saklamanın istediğiniz şekilde inelediğini onaylayın (sahip veya 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": "…" }
}
```

Yanıtta `enabled` ve `data_retention.days`'yi kontrol edin.

> Yanıt ayrıca bir `encryption_algorithm` alanı taşır. **Sadece raporlama**: platformun bekleyen veri şifreleme standardını (Google tarafından yönetilen AES-256, Cloud SQL'de) yansıtır, organizasyon-başı uygulama-katman şifreleme değil. Devotel şu anda mesaj gövdelerinden organizasyon-başı uygulama-katman şifreleme yapmıyor, bu yüzden bu alanı bir auditor'a mesaj gövdelerinin bireysel olarak uygulama katmanında şifrelendiğine kanıt olarak göstermeyin.

## 6. PHI erişim log'unu okuyun

HIPAA modu açıldıktan sonra, PHI içeren verilere her erişim bir append-only audit log'una yazılır. Her giriş kullanıcıyı, kaynağı, neden'i (`read` mesaj okumalarında otomatik kaydedilir) ve zaman damgasını kaydet. `?limit=` ve `?cursor=` ile sayfa — son gördüğünüz girişin `id`'sini sonraki `cursor` olarak geçin (sahip veya 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": "…" }
}
```

Log en fazla 10.000 giriş per organizasyonu en eskileri rotasyona çıkararak tutar, dashboard veya API'den `owner` ve `admin` rollerine erişilebilir ve harici auditler için dışa aktarılabilir. Erken takvime göre inceleyin — erişimin 3. adımdaki rol ve kapsam kararlarını takip ettiğini nasıl kanıtladığınız. `has_more` `true` olduğunda, son girişin `id`'sini `?cursor=` olarak gönderin ve sonraki sayfayı alın.

## 7. HIPAA delil paketini dışa aktarın

Bir auditor'a veya bir alıcının procurement ekibine duruş göstermeniz gerektiğinde, **Ayarlar → Compliance → Binder**'den [delil paketi](/compliance/evidence-binder) HIPAA paketini oluşturun. HIPAA framework PHI erişim log'lamasını, BAA duruşu ve yapılandırılmış saklamayı imzalı, indirmeye hazır bir pakete toplar; her oluşturma audit log'unuza kaydedilir ve indirme linki 24 saat sonra sona erer.

## Sağlık aktivasyon bundle'ı

[Compliance plugin marketplace](/compliance/plugin-marketplace), bir taslak compliance profili, taslak kampanyalar, dikey olarak ayarlanmış bir AI ajanı ve bir opt-in akış yapılandırmasını tek çağrıda provision eden bir **HIPAA sağlık** aktivasyon bundle'ı gönderir. Bu bir başlangıç iskeletidir, bu sıranın yerine geçmez: bundle'ı etkinleştirme BAA'yı asla yürütmez, HIPAA modunu asla etkinleştirmez ve asla bir gönderim yerleşmez. Önce 1–6. adımları üzerinden çalıştırın, sonra bundle'ı etkinleştirin ve go-live checklist'ini taslak'tan production'a çalışın.

## İşlem-sırası checklist'i

* [ ] BAA yürütüldü ve `baa_status` `executed` olarak onaylandı — *sahip rolü*
* [ ] HIPAA modu toggle veya `PUT /settings/hipaa` ile etkinleştirildi — *sahip rolü*
* [ ] Üyelik asgari gerekliye tıraşlandı; `messages:read` sadece ihtitraç eden anahtarlara kapsamlandı — *administratör*
* [ ] `data_retention_days` politika pencerenize ayarlandı — *administratör*
* [ ] Yasal ikamet yükümlülükleriniz ses kaydın nerede olabileceğini kısıtlıyorsa ses bölgesi sabitlendi — *administratör*
* [ ] `GET /settings/hipaa` doğrulandı, `encryption_algorithm` sadece raporlama olarak ele alındı — *compliance sorumlusu*
* [ ] PHI erişim log'u takvime göre incelendi — *compliance sorumlusu*
* [ ] HIPAA delil paketi oluşturuldu ve 24 saatlik link ile teslim edildi — *compliance sorumlusu*