HIPAA onboarding: BAA’dan audit’e hazır

HIPAA kontrolleri 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’lerden 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:

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:

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

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

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

BAA yaşam döngüsü, eski-ayna uyarısı ve tam istek şekilleri 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.

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:

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": "…" }
}

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

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

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

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": "…" }
}

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

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": "…" }
}

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

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

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

HIPAA onboarding: BAA’dan audit’e hazır

1. BAA’yı yürütün

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

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

1c. BAA’nın yürütüldüğünü onaylayın

2. HIPAA modunu etkinleştirin

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

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

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

6. PHI erişim log’unu okuyun

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

Sağlık aktivasyon bundle’ı

İşlem-sırası checklist’i

​HIPAA onboarding: BAA’dan audit’e hazır

​1. BAA’yı yürütün

​1a. PHI’nın kapsamda olduğunu attest edin

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

​1c. BAA’nın yürütüldüğünü onaylayın

​2. HIPAA modunu etkinleştirin

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

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

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

​6. PHI erişim log’unu okuyun

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

​Sağlık aktivasyon bundle’ı

​İşlem-sırası checklist’i

HIPAA onboarding: BAA’dan audit’e hazır

1. BAA’yı yürütün

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

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

1c. BAA’nın yürütüldüğünü onaylayın

2. HIPAA modunu etkinleştirin

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

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

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

6. PHI erişim log’unu okuyun

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

Sağlık aktivasyon bundle’ı

İşlem-sırası checklist’i