Onboarding HIPAA: del BAA a estar listo para auditoría

La referencia de controles HIPAA explica qué hace cada control. Esta guía los pone en orden — la secuencia que lleva a un workspace de salud de “manejamos PHI” a “podemos mostrar un audit trail” sin tropezar con el send gate 422 HIPAA_BAA_REQUIRED — uno de los send gates que verifican la compliance del remitente antes de que se despache un mensaje o una llamada. El orden importa. El modo HIPAA no puede activarse antes de que el BAA se ejecute, los envíos de PHI son rechazados hasta que lo sea, y la retención solo protege datos una vez configurada. Siga los pasos de arriba abajo. Cada paso a continuación se ejecuta contra https://api.orbit.devotel.io/api/v1 con un encabezado X-API-Key en una clave de propietario o administrador. Expórtela antes de empezar:

export ORBIT_KEY="dv_live_sk_…"   # live — o dv_test_sk_… contra el sandbox

Dos convenciones valen para cada respuesta en esta página:

Prefijos de clave. Las claves de sandbox son dv_test_sk_…; las claves live son dv_live_sk_…. Cada llamada a continuación funciona en cualquiera — sandbox devuelve los mismos envelopes sin tocar el estado de compliance en vivo.
Envelope compartido. Cada body de éxito es { "data": { … }, "meta": { "request_id", "timestamp" } }. Los errores son { "error": { code, message, status }, "meta": … }.

1. Ejecutar el BAA

Nada más se desbloquea hasta que la Business Associate Agreement (BAA) esté ejecutada. Dos gates leen el estado del BAA directamente:

Activar el modo HIPAA devuelve 403 Forbidden mientras el estado del BAA no sea executed.
Cualquier envío de PHI es rechazado con 422 HIPAA_BAA_REQUIRED.

Ejecútela a través del panel Compliance → BAA en el dashboard, o impulse las mismas tres llamadas a través de la API. Use una clave de propietario para /execute (vincula el acuerdo legal); una clave de propietario-o-administrador es suficiente para /require y GET /compliance/baa.

1a. Atestar que PHI está en el ámbito

Mueva la organización de not_required a pending, lo que abre el flujo de ejecución:

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 es texto libre opcional registrado en la fila de auditoría, nunca en una columna.

1b. Ejecutar con una firma electrónica de escribir-el-nombre

Registre la atestación. typed_attestation debe coincidir exactamente con signer_name — es la defensa contra una firma accidental o de formulario en blanco:

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. Confirmar que el BAA está ejecutado

Relea el ciclo de vida y anote days_until_expiry — un BAA ejecutado expira tras su período de un año y debe re-ejecutarse:

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); // por ejemplo 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": "…" }
}

El ciclo de vida del BAA, la salvedad del espejo legacy y las formas completas de solicitud están documentados bajo BAA. Para la consola de ejecución, re-ejecución anual y controles de rechazo/reversión — más las consolas hermanas DPA y consentimiento de grabación — vea Ejecutar el DPA y el BAA, luego gestionar el consentimiento de grabación por llamada.

2. Activar el modo HIPAA

Con el BAA ejecutado, active la bandera HIPAA por organización. El modo HIPAA es una bandera de feature por organización que activa cinco controles a la vez — cifrado en reposo, controles de acceso, registro de auditoría PHI, retención forzada y seguimiento de BAA. Esta es una llamada solo de propietario.

Dashboard: Configuración → 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": "…" }
}

Activar es una sola llamada — endurece la postura del workspace, así que no se requiere reto de re-autenticación. Desactivar es destructivo y sí requiere uno; ese flujo está documentado bajo Desactivar el modo HIPAA. Si el estado del BAA no es executed, la llamada devuelve 403 Forbidden.

3. Restringir roles y scopes de API al mínimo necesario

El estándar minimum necessary de HIPAA es su responsabilidad — está del lado del cliente de la tabla de responsabilidad compartida. Los controles de Orbit hoy son gruesos, así que aprovisione para ello honestamente:

Use el rol billing para personal que solo necesita superficies financieras. Los miembros de billing están confinados a facturación, precios y uso — reciben 403 en endpoints de contenido de mensajes.
Tenga en mente el need-to-read de todos los demás: owner, admin, developer y viewer pueden leer contenido de mensajes hoy, y cada lectura aterriza en el registro de acceso PHI.
Emita claves de API solo con los scopes que la integración necesita, y otorgue messages:read solo a servicios que genuinamente leen contenido de mensajes que lleva PHI.

Limitación conocida: Orbit actualmente no restringe las lecturas de contenido de mensajes a un conjunto de roles más estrecho más allá del confinamiento de billing, y los endpoints de lectura de mensajes (GET /messages, GET /messages/{id}) no requieren un código de razón suministrado por el operador. Cumpla el estándar minimum-necessary aprovisionando la membresía del workspace y los scopes de claves API para que solo el personal que necesita PHI pueda alcanzar esos endpoints. Si su programa requiere restricción de lectura por rol sobre contenido de mensajes, contacte a compliance@devotel.io antes de confiar en ello.

4. Configurar la retención de datos

Configure la ventana de retención antes de que PHI se acumule más allá de ella. data_retention_days acepta 30–3.650; el default es 365.

Dashboard: Configuración → Compliance → HIPAA → Retención de datos.
API (solo propietario, mismo endpoint que el toggle):

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

La respuesta repite el objeto de estado completo (misma forma que la llamada de activación arriba); verifique data.data_retention.days. Un job en segundo plano escanea contenido de mensajes, grabaciones de llamadas y adjuntos de medios caducados y los elimina. Los logs de auditoría y los logs de acceso PHI se retienen independientemente de esta política — el reloj de eliminación no borra su pista de evidencia. Si graba llamadas, fije la región de voz para que coincida con sus obligaciones de residencia al mismo tiempo — vea Residencia y retención de datos de voz para el control de residencia que mantiene grabaciones, buzón de voz y medios en vivo en una región.

5. Verificar la configuración

Confirme que la bandera y la retención aterrizaron como usted pretendía (propietario o administrador):

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

Verifique enabled y data_retention.days en la respuesta.

La respuesta también lleva un campo encryption_algorithm. Es solo para informe: refleja el estándar de cifrado en reposo de la plataforma (AES-256 gestionado por Google en Cloud SQL), no un cifrador de capa de aplicación por organización. Devotel actualmente no realiza cifrado de capa de aplicación por organización de los cuerpos de mensaje, así que no cite este campo ante un auditor como evidencia de que los cuerpos de mensaje están individualmente cifrados en la capa de aplicación.

6. Leer el registro de acceso PHI

Una vez que el modo HIPAA está activado, cada acceso a datos que contienen PHI es escrito en un log de auditoría append-only. Cada entrada registra el usuario, el recurso, la razón (read se registra automáticamente en lecturas de mensajes) y el timestamp. Página con ?limit= y ?cursor= — pase el id de la última entrada que vio como el siguiente cursor (propietario o administrador):

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

El log retiene hasta 10.000 entradas por organización con las más antiguas rotadas fuera, es accesible a los roles owner y admin vía el dashboard o la API, y puede exportarse para auditorías externas. Revíselo en un calendario temprano — es como demuestra que el acceso sigue las decisiones de rol y scope que tomó en el paso 3. Cuando has_more es true, envíe el id de la última entrada como ?cursor= para la siguiente página.

7. Exportar el binder de evidencia HIPAA

Cuando necesite mostrar postura a un auditor o al equipo de procurement de un comprador, genere el pack HIPAA del binder de evidencia desde Configuración → Compliance → Binder. El framework HIPAA ensambla el registro de acceso PHI, la postura BAA y su retención configurada en un pack firmado y listo para descargar; cada generación se registra en su log de auditoría, y el enlace de descarga expira tras 24 horas.

Bundle de activación healthcare

El marketplace de plugins de compliance envía un bundle de activación HIPAA healthcare que aprovisiona un perfil de compliance en borrador, campañas en borrador, un agente AI ajustado a la vertical y una configuración de flujo opt-in en una llamada. Es un andamiaje inicial, no un sustituto de esta secuencia: activar el bundle nunca ejecuta el BAA, nunca activa el modo HIPAA y nunca coloca un envío. Ejecute los pasos 1–6 arriba primero, luego active el bundle y trabaje su checklist go-live de borrador a producción.

Checklist de orden de operaciones

BAA ejecutado y baa_status confirmado como executed — rol propietario
Modo HIPAA activado vía el toggle o PUT /settings/hipaa — rol propietario
Membresía recortada al mínimo necesario; messages:read con scope solo a claves que lo necesitan — administrador
data_retention_days fijado a su ventana de política — administrador
Región de voz fijada si sus obligaciones de residencia restringen dónde pueden vivir el audio grabado — administrador
GET /settings/hipaa verificado, con encryption_algorithm tratado como solo-informe — oficial de compliance
Registro de acceso PHI revisado en calendario — oficial de compliance
Binder de evidencia HIPAA generado y entregado a través del enlace de 24 horas — oficial de compliance

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Onboarding HIPAA: del BAA a estar listo para auditoría

Onboarding HIPAA: del BAA a estar listo para auditoría

1. Ejecutar el BAA

1a. Atestar que PHI está en el ámbito

1b. Ejecutar con una firma electrónica de escribir-el-nombre

1c. Confirmar que el BAA está ejecutado

2. Activar el modo HIPAA

3. Restringir roles y scopes de API al mínimo necesario

4. Configurar la retención de datos

5. Verificar la configuración

6. Leer el registro de acceso PHI

7. Exportar el binder de evidencia HIPAA

Bundle de activación healthcare

Checklist de orden de operaciones

​Onboarding HIPAA: del BAA a estar listo para auditoría

​1. Ejecutar el BAA

​1a. Atestar que PHI está en el ámbito

​1b. Ejecutar con una firma electrónica de escribir-el-nombre

​1c. Confirmar que el BAA está ejecutado

​2. Activar el modo HIPAA

​3. Restringir roles y scopes de API al mínimo necesario

​4. Configurar la retención de datos

​5. Verificar la configuración

​6. Leer el registro de acceso PHI

​7. Exportar el binder de evidencia HIPAA

​Bundle de activación healthcare

​Checklist de orden de operaciones

Onboarding HIPAA: del BAA a estar listo para auditoría

1. Ejecutar el BAA

1a. Atestar que PHI está en el ámbito

1b. Ejecutar con una firma electrónica de escribir-el-nombre

1c. Confirmar que el BAA está ejecutado

2. Activar el modo HIPAA

3. Restringir roles y scopes de API al mínimo necesario

4. Configurar la retención de datos

5. Verificar la configuración

6. Leer el registro de acceso PHI

7. Exportar el binder de evidencia HIPAA

Bundle de activación healthcare

Checklist de orden de operaciones