HIPAA onboarding: BAA’den denetime hazır duruma

HIPAA kontrolleri başvurusu her kontrolün ne yaptığını açıklar. Bu kılavuz, onları sıraya koyan resmi uçtan uca anlatımdır — bir sağlık çalışma alanını “PHI ele alıyoruz”dan “bir denetim izi gösterebiliriz”e, 422 HIPAA_BAA_REQUIRED gönderim kapısına takılmadan taşıyan sıra. İlk etkinleştirme el kitabı, aynı sırayı buradaki örnekleri tekrarlamadan operasyona veren yalnızca-kontrol-listesi eşlikçisidir. Sıra önemlidir. HIPAA modu, BAA imzalanmadan etkinleştirilemez; PHI gönderimleri o imzalanana dek reddedilir ve saklama süresi, ancak yapılandırıldıktan sonra veriyi korur. Adımları yukarıdan aşağıya izleyin. Aşağıdaki her adım, owner veya admin anahtarında bir X-API-Key başlığıyla https://api.orbit.devotel.io/api/v1’e karşı çalışır. Başlamadan dışa aktarın:

export ORBIT_KEY="dv_live_sk_…"   # live — or dv_test_sk_… against the sandbox

Bu sayfadaki her yanıt için iki kural geçerlidir:

Anahtar önekleri. Sandbox anahtarları dv_test_sk_…; canlı anahtarlar dv_live_sk_…. Aşağıdaki her çağrı ikisinde de çalışır — sandbox, canlı uyum durumuna dokunmadan aynı zarfları döndürür.
Paylaşılan zarf. Her başarı gövdesi { "data": { … }, "meta": { "request_id", "timestamp" } } şeklindedir. Hatalar { "error": { code, message, status }, "meta": … } şeklindedir.

1. BAA’i imzalayın

Business Associate Agreement (BAA) imzalanana dek başka hiçbir şey açılmaz. İki kapı BAA durumunu doğrudan okur:

HIPAA modunu etkinleştirme, BAA durumu executed değilken 403 Forbidden döndürür.
Herhangi bir PHI gönderimi 422 HIPAA_BAA_REQUIRED ile reddedilir.

Paneldeki Compliance → BAA bölmesi üzerinden imzalayın veya aynı üç çağrıyı API üzerinden sürün. /execute için bir owner anahtarı kullanın (yasal anlaşmayı bağlar); /require ve GET /compliance/baa için owner-veya-admin anahtarı yeterlidir.

1a. PHI’nin kapsamda olduğunu beyan edin

Organizasyonu not_required’dan pending’e taşıyın; bu, imza 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, denetim satırına kaydedilen isteğe bağlı serbest metindir; asla bir sütuna yazılmaz.

1b. Adı yazarak e-imza ile imzalayın

Beyanı kaydedin. typed_attestation, signer_name ile birebir eşleşmelidir — kazara veya boş form imzasına karşı savunma budur:

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’in imzalı olduğunu doğrulayın

Yaşam döngüsünü yeniden okuyun ve days_until_expiry’e dikkat edin — imzalı bir BAA bir yıllık süresinin sonunda süresi dolar ve yeniden imzalanmalıdır:

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); // e.g. 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 belgelenmiştir. İmzanın, yıllık yeniden imzanın ve reddetme/geri alma kontrollerinin konsol anlatımı — artı kardeş DPA ve kayıt onayı konsolları — için bkz. Execute the DPA and BAA, then manage per-call recording consent.

2. HIPAA modunu etkinleştirin

BAA imzalıyken, organizasyon başına HIPAA bayrağını açın. HIPAA modu, beş kontrolü birden etkinleştiren organizasyon başına bir özellik bayrağıdır — dururken şifreleme, erişim kontrolleri, PHI denetim kaydı, zorunlu saklama süresi ve BAA izleme. Bu, yalnızca owner çağrısıdır.

Panel: Settings → Compliance → HIPAA Mode Toggle.
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": "…" }
}

Etkinleştirme tek bir çağrıdır — çalışma alanının duruşunu sıkılaştırır, bu yüzden yeniden kimlik doğrulama meydan okuması gerekmez. Devre dışı bırakma yıkıcıdır ve bir tane gerektirir; bu akış Disabling HIPAA Mode altında belgelenmiştir. BAA durumu executed değilse, çağrı 403 Forbidden döndürür.

3. Roller ve API kapsamlarını asgari gerekliliğe sınırlayın

HIPAA’nın asgari gerekli standardı sizin sorumluluğunuzdur — paylaşılan sorumluluk tablosunun müşteri tarafında durur. Orbit’in kontrolleri bugün kabadır; bu yüzden buna dürüstçe hüküm verin:

Yalnızca finans yüzeylerine ihtiyacı olan personel için billing rolünü kullanın. Billing üyeleri faturalama, fiyatlandırma ve kullanım ile sınırlanır; mesaj içeriği uç noktalarında 403 alırlar.
Diğer herkesin okuma gereksinimini akılda tutun: owner, admin, developer ve viewer bugün mesaj içeriğinin tümünü okuyabilir ve her okuma PHI erişim kaydına düşer.
API anahtarlarını yalnızca entegrasyonun ihtiyaç duyduğu kapsamlarla üretin ve messages:read’i yalnızca PHI taşıyan mesaj içeriğini gerçekten okuyan servislere verin.

Bilinen sınırlılık: Orbit şu anda mesaj içeriği okumalarını, billing sınırlamasının ötesinde daha dar bir rol kümesine kısıtlamaz ve mesaj okuma uç noktaları (GET /messages, GET /messages/{id}) operatörce verilen bir gerekçe kodu istemez. Asgari gerekli standardını, çalışma alanı üyeliğini ve API anahtarı kapsamlarını yalnızca PHI’ye ihtiyacı olan personel bu uç noktalara ulaşabilecek şekilde hüküm vererek karşılayın. Programınız mesaj içeriğinde rol başına okuma kısıtlaması gerektiriyorsa, ona güvenmeden önce support@orbit.devotel.io ile iletişime geçin.

4. Veri saklama süresini yapılandırın

Saklama penceresini, PHI onun ötesinde birikmeden önce kurun. data_retention_days 30–3,650 kabul eder; öntanım 365’tir.

Panel: Settings → Compliance → HIPAA → Data Retention.
API (yalnızca owner, anahtarla aynı uç nokta):

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 yankılar (yukarıdaki etkinleştirme çağrısıyla aynı şekil); data.data_retention.days değerini kontrol edin. Bir arka plan işi, süresi dolmuş mesaj içeriğini, arama kayıtlarını ve medya eklerini tarar ve siler. Denetim kayıtları ve PHI erişim kayıtları bu politikadan bağımsız saklanır — silme saati kanıt izinizi silmez. Arama kaydediyorsanız, aynı anda ses bölgesini ikame yükümlülüklerinizle eşleşecek şekilde sabitleyin — kayıtları, sesli postayı ve canlı medyayı tek bir bölgede tutan ikame ayarı için bkz. Voice Data Residency & Retention.

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

Bayrağın ve saklama süresinin amaçladığınız gibi indiğini doğrulayın (owner 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 değerlerini kontrol edin.

Yanıt ayrıca bir encryption_algorithm alanı taşır. Bu yalnızca raporlamadır: platformun dururken şifreleme standardını yansıtır (Cloud SQL üzerinde Google yönetimli AES-256), organizasyon başına bir uygulama katmanı şifresi değil. Devotel şu anda mesaj gövdelerinin organizasyon başına uygulama katmanı şifrelemesini yapmaz; bu yüzden bu alanı bir denetçiye, mesaj gövdelerinin uygulama katmanında tek tek şifrelendiğinin kanıtı olarak göstermeyin.

6. PHI erişim kaydını okuyun

HIPAA modu açıkken, PHI içeren verilere her erişim, yalnızca eklenen bir denetim kaydına yazılır. Her girdi kullanıcıyı, kaynağı, nedeni (read, mesaj okumalarında otomatik kaydedilir) ve zaman damgasını kaydeder. ?limit= ve ?cursor= ile sayfalam yapın — gördüğünüz son girdinin id’sini sonraki cursor olarak geçirin (owner 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": "…" }
}

Kayıt, organizasyon başına en çok 10,000 girdi tutar ve en eskiler dönüşümlü çıkarılır; panel veya API üzerinden owner ve admin rollerine erişilebilir ve dış denetimler için dışa aktarılabilir. Erken bir takvimle gözden geçirin — erişimin, 3. adımda aldığınız rol ve kapsam kararlarını izlediğini kanıtlamanın yolu budur. has_more true iken, sonraki sayfayı getirmek için son girdinin id’sini ?cursor= olarak gönderin.

7. HIPAA kanıt dosyasını dışa aktarın

Bir denetçiye veya bir alıcının tedarik ekibine duruş göstermeniz gerektiğinde, Settings → Compliance → Binder’dan kanıt dosyasının HIPAA paketini üretin. HIPAA çerçevesi, PHI erişim kaydını, BAA duruşunu ve yapılandırdığınız saklama süresini imzalı, indirmeye hazır bir pakette birleştirir; her üretim denetim kaydınıza yazılır ve indirme bağlantısı 24 saat sonra süresi dolar.

Sağlık etkinleştirme paketi

Uyum eklenti pazar yeri, tek çağrıda bir taslak uyum profili, taslak kampanyalar, sektöre ayarlı bir AI ajanı ve bir opt-in akış yapılandırması sağlayan bir HIPAA healthcare etkinleştirme paketi gönderir. Bu sıranın yerine geçen değil, bir başlangıç iskelesidir: paketi etkinleştirmek asla BAA’i imzalamaz, asla HIPAA modunu açmaz ve asla bir gönderim yerleştirmez. Paketi etkinleştirmeden önce yukarıdaki 1–6 adımlarını yürütün, ardından paketi etkinleştirip onun go-live kontrol listesini taslaktan üretime çalışın.

İşlem sırası kontrol listesi

BAA imzalı ve baa_status executed olarak doğrulanmış — owner rolü
HIPAA modu anahtarla veya PUT /settings/hipaa ile etkin — owner rolü
Üyelik asgari gerekliliğe budanmış; messages:read yalnızca ihtiyacı olan anahtarlara kapsamlanmış — yönetici
data_retention_days politika pencerenize kurulu — yönetici
İkame yükümlülükleriniz kaydedilen sesin nerede yaşayabileceğini kısıtlıyorsa ses bölgesi sabitlenmiş — yönetici
GET /settings/hipaa doğrulanmış ve encryption_algorithm yalnızca raporlama olarak ele alınmış — uyum sorumlusu
PHI erişim kaydı bir takvimle gözden geçiriliyor — uyum sorumlusu
HIPAA kanıt dosyası üretilmiş ve 24 saatlik bağlantıyla teslim edilmiş — uyum sorumlusu

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

HIPAA onboarding: BAA'den denetime hazır duruma

HIPAA onboarding: BAA’den denetime hazır duruma

1. BAA’i imzalayın

1a. PHI’nin kapsamda olduğunu beyan edin

1b. Adı yazarak e-imza ile imzalayın

1c. BAA’in imzalı olduğunu doğrulayın

2. HIPAA modunu etkinleştirin

3. Roller ve API kapsamlarını asgari gerekliliğe sınırlayın

4. Veri saklama süresini yapılandırın

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

6. PHI erişim kaydını okuyun

7. HIPAA kanıt dosyasını dışa aktarın

Sağlık etkinleştirme paketi

İşlem sırası kontrol listesi

​HIPAA onboarding: BAA’den denetime hazır duruma

​1. BAA’i imzalayın

​1a. PHI’nin kapsamda olduğunu beyan edin

​1b. Adı yazarak e-imza ile imzalayın

​1c. BAA’in imzalı olduğunu doğrulayın

​2. HIPAA modunu etkinleştirin

​3. Roller ve API kapsamlarını asgari gerekliliğe sınırlayın

​4. Veri saklama süresini yapılandırın

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

​6. PHI erişim kaydını okuyun

​7. HIPAA kanıt dosyasını dışa aktarın

​Sağlık etkinleştirme paketi

​İşlem sırası kontrol listesi

HIPAA onboarding: BAA’den denetime hazır duruma

1. BAA’i imzalayın

1a. PHI’nin kapsamda olduğunu beyan edin

1b. Adı yazarak e-imza ile imzalayın

1c. BAA’in imzalı olduğunu doğrulayın

2. HIPAA modunu etkinleştirin

3. Roller ve API kapsamlarını asgari gerekliliğe sınırlayın

4. Veri saklama süresini yapılandırın

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

6. PHI erişim kaydını okuyun

7. HIPAA kanıt dosyasını dışa aktarın

Sağlık etkinleştirme paketi

İşlem sırası kontrol listesi