Onboarding HIPAA : du BAA à l’audit-ready

La référence HIPAA controls explique ce que fait chaque contrôle. Ce guide est le parcours canonique de bout en bout qui les met en ordre — la séquence qui fait passer un espace de travail santé de “nous traitons des PHI” à “nous pouvons montrer une piste d’audit” sans déclencher le gate d’envoi 422 HIPAA_BAA_REQUIRED. Le runbook de première activation est le compagnon en checklist qui remet la même séquence aux opérations sans répéter les exemples ici. L’ordre compte. Le mode HIPAA ne peut pas être activé avant que le BAA soit exécuté, les envois de PHI sont rejetés tant qu’il ne l’est pas, et la rétention ne protège les données qu’une fois configurée. Suivez les étapes de haut en bas. Chaque étape ci-dessous s’exécute contre https://api.orbit.devotel.io/api/v1 avec un en-tête X-API-Key sur une clé owner ou admin. Exportez-la avant de commencer :

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

Deux conventions valent pour chaque réponse de cette page :

Préfixes de clé. Les clés sandbox sont dv_test_sk_… ; les clés live sont dv_live_sk_…. Chaque appel ci-dessous fonctionne sur les deux — le sandbox renvoie les mêmes enveloppes sans toucher à l’état de conformité live.
Enveloppe partagée. Chaque corps de succès est { "data": { … }, "meta": { "request_id", "timestamp" } }. Les erreurs sont { "error": { code, message, status }, "meta": … }.

1. Exécuter le BAA

Rien d’autre ne se débloque tant que le Business Associate Agreement (BAA) n’est pas exécuté. Deux gates lisent directement le statut du BAA :

Activer le mode HIPAA renvoie 403 Forbidden tant que le statut BAA n’est pas executed.
Tout envoi de PHI est rejeté avec 422 HIPAA_BAA_REQUIRED.

Exécutez-le par le panneau Compliance → BAA du tableau de bord, ou pilotez les mêmes trois appels par l’API. Utilisez une clé owner pour /execute (elle lie l’accord juridique) ; une clé owner-ou-admin suffit pour /require et GET /compliance/baa.

1a. Attester que les PHI sont dans le périmètre

Faites passer l’organisation de not_required à pending, ce qui ouvre le flux d’exécution :

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 est un texte libre optionnel consigné sur la ligne d’audit, jamais sur une colonne.

1b. Exécuter avec une signature électronique tapée

Consignez l’attestation. typed_attestation doit correspondre exactement à signer_name — c’est la défense contre une signature accidentelle ou sur formulaire vide :

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. Confirmer que le BAA est exécuté

Relisez le cycle de vie et notez days_until_expiry — un BAA exécuté expire après son terme d’un an et doit être ré-exécuté :

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

Le cycle de vie du BAA, la réserve du miroir legacy et les formes complètes de requête sont documentés sous BAA. Pour le parcours console de l’exécution, de la ré-exécution annuelle et des contrôles de déclin/retour — plus les consoles sœurs DPA et consentement d’enregistrement — voir Execute the DPA and BAA, then manage per-call recording consent.

2. Activer le mode HIPAA

Une fois le BAA exécuté, activez le drapeau HIPAA par organisation. Le mode HIPAA est un feature flag par organisation qui active cinq contrôles d’un coup — chiffrement au repos, contrôles d’accès, journalisation d’audit PHI, rétention imposée et suivi du BAA. C’est un appel owner uniquement.

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

L’activation est un appel unique — elle resserre la posture de l’espace de travail, donc aucun défi de ré-authentification n’est requis. La désactivation est destructrice et en exige un ; ce flux est documenté sous Disabling HIPAA Mode. Si le statut BAA n’est pas executed, l’appel renvoie 403 Forbidden.

3. Restreindre rôles et scopes API au minimum nécessaire

Le standard minimum nécessaire de HIPAA est votre responsabilité — il siège du côté client du tableau de responsabilité partagée. Les contrôles d’Orbit sont aujourd’hui grossiers, alors provisionnez-le honnêtement :

Utilisez le rôle billing pour le personnel qui n’a besoin que des surfaces financières. Les membres billing sont confinés à la facturation, aux tarifs et à l’usage — ils reçoivent 403 sur les points d’entrée de contenu de messages.
Gardez en tête le besoin de lecture des autres : owner, admin, developer et viewer peuvent tous lire le contenu des messages aujourd’hui, et chaque lecture atterrit dans le journal d’accès PHI.
Émettez des clés API avec seulement les scopes dont l’intégration a besoin, et n’accordez messages:read qu’aux services qui lisent réellement du contenu de messages porteur de PHI.

Limitation connue : Orbit ne restreint pas actuellement les lectures de contenu de messages à un jeu de rôles plus étroit au-delà du confinement billing, et les points d’entrée de lecture de messages (GET /messages, GET /messages/{id}) n’exigent pas de code de raison fourni par l’opérateur. Respectez le standard du minimum nécessaire en provisionnant l’appartenance à l’espace de travail et les scopes de clés API de sorte que seul le personnel qui a besoin des PHI puisse atteindre ces points d’entrée. Si votre programme exige une restriction de lecture par rôle sur le contenu des messages, contactez support@orbit.devotel.io avant de vous y fier.

4. Configurer la rétention des données

Fixez la fenêtre de rétention avant que des PHI ne s’accumulent au-delà. data_retention_days accepte 30 à 3 650 ; le défaut est 365.

Tableau de bord : Settings → Compliance → HIPAA → Data Retention.
API (owner uniquement, même point d’entrée que le 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 réponse renvoie en écho l’objet de statut complet (même forme que l’appel d’activation ci-dessus) ; vérifiez data.data_retention.days. Un job d’arrière-plan cherche les contenus de messages, enregistrements d’appels et pièces jointes multimédia expirés et les supprime. Les journaux d’audit et les journaux d’accès PHI sont conservés indépendamment de cette politique — l’horloge de suppression n’efface pas votre piste de preuves. Si vous enregistrez des appels, épinglez la région voix pour aligner vos obligations de résidence au même moment — voir Voice Data Residency & Retention pour le réglage de résidence qui garde enregistrements, messagerie vocale et médias en direct dans une seule région.

5. Vérifier la configuration

Confirmez que le drapeau et la rétention ont atterri comme vous l’entendiez (owner ou 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": "…" }
}

Vérifiez enabled et data_retention.days dans la réponse.

La réponse porte aussi un champ encryption_algorithm. Il est de rapport uniquement : il reflète le standard de chiffrement au repos de la plateforme (AES-256 géré par Google sur Cloud SQL), pas un chiffrement de couche applicative par organisation. Devotel ne réalise pas actuellement de chiffrement de couche applicative des corps de messages par organisation, donc ne citez pas ce champ à un auditeur comme preuve que les corps de messages sont chiffrés individuellement à la couche applicative.

6. Lire le journal d’accès PHI

Une fois le mode HIPAA activé, chaque accès à des données contenant des PHI est écrit dans un journal d’audit en ajout seul. Chaque entrée consigne l’utilisateur, la ressource, la raison (read est consigné automatiquement sur les lectures de messages) et l’horodatage. Parcourez-le par pages avec ?limit= et ?cursor= — passez l’id de la dernière entrée vue comme prochain cursor (owner ou 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": "…" }
}

Le journal conserve jusqu’à 10 000 entrées par organisation, les plus anciennes étant sorties par rotation, est accessible aux rôles owner et admin par le tableau de bord ou l’API, et peut être exporté pour des audits externes. Passez-le en revue selon un planning tôt — c’est ainsi que vous démontrez que l’accès suit les décisions de rôles et de scopes prises à l’étape 3. Quand has_more vaut true, envoyez l’id de la dernière entrée comme ?cursor= pour récupérer la page suivante.

7. Exporter le classeur de preuves HIPAA

Quand vous devez montrer votre posture à un auditeur ou à l’équipe achats d’un acheteur, générez le pack HIPAA du classeur de preuves depuis Settings → Compliance → Binder. Le framework HIPAA assemble la journalisation d’accès PHI, la posture BAA et votre rétention configurée en un pack signé, prêt à télécharger ; chaque génération est consignée dans votre journal d’audit, et le lien de téléchargement expire après 24 heures.

Bundle d’activation healthcare

La place de marché de plugins de conformité livre un bundle d’activation HIPAA healthcare qui provisionne en un appel un profil de conformité en brouillon, des campagnes en brouillon, un agent IA accordé au secteur et une configuration de flux d’opt-in. C’est un échafaudage de départ, pas un substitut à cette séquence : activer le bundle n’exécute jamais le BAA, n’active jamais le mode HIPAA et ne pose jamais un envoi. Exécutez d’abord les étapes 1 à 6 ci-dessus, puis activez le bundle et faites passer sa checklist de mise en production du brouillon à la production.

Checklist d’ordre des opérations

BAA exécuté et baa_status confirmé à executed — rôle owner
Mode HIPAA activé par le toggle ou PUT /settings/hipaa — rôle owner
Appartenance réduite au minimum nécessaire ; messages:read scopé aux seules clés qui en ont besoin — administrator
data_retention_days fixé à votre fenêtre de politique — administrator
Région voix épinglée si vos obligations de résidence restreignent où l’audio enregistré peut vivre — administrator
GET /settings/hipaa vérifié, avec encryption_algorithm traité comme de rapport uniquement — compliance officer
Journal d’accès PHI passé en revue selon un planning — compliance officer
Classeur de preuves HIPAA généré et transmis par le lien de 24 heures — compliance officer

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

Onboarding HIPAA : du BAA à l'audit-ready

Onboarding HIPAA : du BAA à l’audit-ready

1. Exécuter le BAA

1a. Attester que les PHI sont dans le périmètre

1b. Exécuter avec une signature électronique tapée

1c. Confirmer que le BAA est exécuté

2. Activer le mode HIPAA

3. Restreindre rôles et scopes API au minimum nécessaire

4. Configurer la rétention des données

5. Vérifier la configuration

6. Lire le journal d’accès PHI

7. Exporter le classeur de preuves HIPAA

Bundle d’activation healthcare

Checklist d’ordre des opérations

​Onboarding HIPAA : du BAA à l’audit-ready

​1. Exécuter le BAA

​1a. Attester que les PHI sont dans le périmètre

​1b. Exécuter avec une signature électronique tapée

​1c. Confirmer que le BAA est exécuté

​2. Activer le mode HIPAA

​3. Restreindre rôles et scopes API au minimum nécessaire

​4. Configurer la rétention des données

​5. Vérifier la configuration

​6. Lire le journal d’accès PHI

​7. Exporter le classeur de preuves HIPAA

​Bundle d’activation healthcare

​Checklist d’ordre des opérations

Onboarding HIPAA : du BAA à l’audit-ready

1. Exécuter le BAA

1a. Attester que les PHI sont dans le périmètre

1b. Exécuter avec une signature électronique tapée

1c. Confirmer que le BAA est exécuté

2. Activer le mode HIPAA

3. Restreindre rôles et scopes API au minimum nécessaire

4. Configurer la rétention des données

5. Vérifier la configuration

6. Lire le journal d’accès PHI

7. Exporter le classeur de preuves HIPAA

Bundle d’activation healthcare

Checklist d’ordre des opérations