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

> Devotel's HIPAA readiness controls for protecting healthcare communications

# HIPAA Compliance

Devotel provides HIPAA-ready infrastructure for organizations that handle Protected Health Information (PHI) through communication channels. This document describes the technical and administrative controls implemented when HIPAA mode is enabled.

***

## Overview

HIPAA mode is a **per-organization feature flag** that activates a set of enhanced security controls:

1. **Encryption at Rest** — PHI encrypted at rest with Google-managed AES-256 (Cloud SQL default)
2. **Access Controls** — PHI access restricted to designated roles
3. **Audit Logging** — All PHI access logged with reason codes
4. **Data Retention** — Automatic deletion after configured retention period
5. **BAA Tracking** — Business Associate Agreement status management

## Prerequisites

Before enabling HIPAA mode, organizations must:

1. **Sign a Business Associate Agreement (BAA)** with Devotel
2. Designate a **HIPAA compliance officer** within their team

***

## Technical Controls

### 1. Encryption at Rest

All PHI — including message `body`, `media_url`, and metadata — is encrypted at rest using **Google-managed AES-256** keys (Cloud SQL default encryption):

* **Algorithm**: AES-256 (Google Cloud default at-rest encryption)
* **Key Management**: Encryption keys are managed and rotated by Google Cloud
* **Scope**: All database-stored content, including message `body`, `media_url`, and metadata
* **In transit**: TLS 1.3 protects all data in transit (see [Infrastructure Safeguards](#infrastructure-safeguards))

> **Note**: Devotel does not currently perform per-organization application-layer encryption of message bodies. PHI confidentiality at rest relies on Google Cloud's transparent AES-256 encryption rather than an application-layer cipher. The `GET /settings/hipaa` response includes an `encryption_algorithm` field for reporting purposes only — it does **not** indicate that message bodies are individually encrypted at the application layer.

### 2. Access Controls

Message-content reads are governed by workspace membership and, for API keys, by the `messages:read` / `messages:write` scope. Every read is recorded in the [PHI access log](#3-phi-access-audit-log). The table below reflects who can read message content today:

| Role        | Message-content read | Notes                                                                       |
| ----------- | -------------------- | --------------------------------------------------------------------------- |
| `owner`     | Yes                  | Can enable/disable HIPAA mode and view PHI access logs                      |
| `admin`     | Yes                  | Can view PHI access logs                                                    |
| `developer` | Yes                  | Each read is recorded in the PHI access log                                 |
| `viewer`    | Yes                  | Each read is recorded in the PHI access log                                 |
| `billing`   | No                   | Confined to financial surfaces; receives `403` on message-content endpoints |

The `billing` role is limited to financial surfaces — billing, pricing, and usage insights — and cannot read message content. Every other role, including `viewer`, can read message content, and each access is written to the PHI access log.

Reason codes are stored on every PHI access-log entry. Reads through `GET /messages` and `GET /messages/{id}` are recorded with an automatic `read` reason. The categories below describe the access reasons used elsewhere in the platform when an operator supplies one explicitly:

* `treatment` — Access required for patient treatment coordination
* `payment` — Access required for payment processing
* `operations` — Access required for healthcare operations
* `legal` — Access required for legal compliance
* `support` — Access required for customer support resolution

> **Known limitation:** Orbit does not currently restrict message-content reads to a narrower set of roles beyond the `billing` confinement above, and it does not require an operator-supplied reason code on the message read endpoints (`GET /messages`, `GET /messages/{id}`). To meet the HIPAA *minimum necessary* standard, provision workspace membership and API-key scopes so that only staff who need PHI can reach these endpoints. If your program requires per-role read restriction on message content, contact [compliance@devotel.io](mailto:compliance@devotel.io) before relying on it.

### 3. PHI Access Audit Log

Every access to PHI-containing data generates an audit log entry:

```json theme={null}
{
  "id": "phi_abc123",
  "userId": "usr_xyz789",
  "resource": "message:msg_def456",
  "reason": "treatment",
  "accessedAt": "2026-04-02T10:30:00Z"
}
```

The PHI access log:

* Is **append-only** and cannot be modified or deleted
* Retains up to **10,000 entries** per organization (oldest entries are automatically rotated)
* Is accessible to `owner` and `admin` roles via the dashboard or API
* Can be exported for external compliance audits

**API Endpoint**: `GET /api/v1/settings/hipaa/phi-access-log`

### 4. Data Retention

When HIPAA mode is active, data retention is enforced:

* **Default retention period**: 365 days (configurable: 30–3,650 days)
* **Scope**: Message content, call recordings, media attachments
* **Mechanism**: Automated background job scans for expired records and securely deletes them
* **Exceptions**: Audit logs and PHI access logs are retained independently of the data retention policy

**Configuration**: Via dashboard at **Settings → Compliance → HIPAA → Data Retention** or via API:

```bash theme={null}
PUT /api/v1/settings/hipaa
{
  "enabled": true,
  "data_retention_days": 365
}
```

**Enabling** HIPAA mode is a single call — it tightens the workspace's security posture, so no re-authentication challenge is required (a signed BAA is still mandatory; see below). **Disabling** HIPAA mode is destructive and requires the two-step re-auth flow described in [Disabling HIPAA Mode](#6-disabling-hipaa-mode).

### 5. Business Associate Agreement (BAA)

Devotel tracks BAA status per organization:

* **Status**: Signed / Not signed
* **Signed date**: Recorded when BAA is confirmed
* **Document URL**: Optional link to the signed BAA document

**Requirement**: HIPAA mode **cannot be enabled** without a signed BAA. Attempting to enable HIPAA mode without a BAA returns a `403 Forbidden` error.

**API Endpoint**: `PUT /api/v1/settings/hipaa/baa`

```bash theme={null}
PUT /api/v1/settings/hipaa/baa
{
  "signed": true,
  "signed_at": "2026-04-01T00:00:00Z",
  "document_url": "https://storage.devotel.io/baa/org_abc123.pdf"
}
```

### 6. Disabling HIPAA Mode

Disabling HIPAA mode is a **destructive, audit-sensitive** transition: it clears the covered-entity flag, the BAA link, and the strict retention floor on a workspace that may hold PHI. To prevent this from happening on a stolen browser session, disabling requires a **fresh re-authentication challenge**. (Enabling HIPAA mode does *not* — it only tightens posture.)

Disabling is therefore a **two-step** flow:

**Step 1 — Mint a single-use re-auth challenge token:**

```bash theme={null}
POST /api/v1/settings/hipaa/reauth-challenge
```

The response returns a short-lived (5-minute), single-use token:

```json theme={null}
{
  "challenge_token": "h7Yc...base64url...",
  "expires_at": "2026-04-02T10:35:00Z"
}
```

**Step 2 — Send the disable request with the `X-Reauth-Challenge` header set to that token:**

```bash theme={null}
PUT /api/v1/settings/hipaa
X-Reauth-Challenge: h7Yc...base64url...
{
  "enabled": false
}
```

The token must be redeemed **within 5 minutes** and can be consumed only **once**. If the `X-Reauth-Challenge` header is missing, malformed, or expired, the disable request is rejected with `401 REAUTH_REQUIRED`:

```json theme={null}
{
  "error": {
    "code": "REAUTH_REQUIRED",
    "message": "Fresh re-authentication is required to disable HIPAA mode. POST /settings/hipaa/reauth-challenge first, then retry within 5 minutes with X-Reauth-Challenge header."
  }
}
```

> **Note:** The re-auth challenge gates only the **enable → disable** transition. Enabling HIPAA mode, and retention-only updates submitted while HIPAA mode is already disabled, do **not** require the header.

***

## API Reference

| Method | Endpoint                           | Description                                                        | Required Role |
| ------ | ---------------------------------- | ------------------------------------------------------------------ | ------------- |
| `GET`  | `/settings/hipaa`                  | Get HIPAA status and configuration                                 | `admin+`      |
| `PUT`  | `/settings/hipaa`                  | Enable/disable HIPAA mode (disable requires `X-Reauth-Challenge`)  | `owner`       |
| `POST` | `/settings/hipaa/reauth-challenge` | Mint a single-use re-auth token required to **disable** HIPAA mode | `owner`       |
| `GET`  | `/settings/hipaa/phi-access-log`   | Paginated PHI access log                                           | `admin+`      |
| `PUT`  | `/settings/hipaa/baa`              | Update BAA status                                                  | `owner`       |

***

## Dashboard Configuration

HIPAA settings are available in the dashboard under **Settings → Compliance**:

1. **HIPAA Mode Toggle** — Enable/disable HIPAA mode (requires BAA)
2. **BAA Section** — Track BAA signing status and date
3. **Data Retention** — Configure automatic data deletion period
4. **PHI Access Log** — View and export PHI access audit trail

***

## Infrastructure Safeguards

Beyond application-level controls, Devotel's infrastructure provides:

* **Cloud SQL Encryption**: All database storage encrypted with AES-256 by Google Cloud
* **TLS 1.3**: All data in transit encrypted with TLS 1.3
* **VPC Isolation**: Database accessible only via private IP within the VPC
* **No Privileged Containers**: GKE Autopilot prevents privileged container execution
* **Secret Manager**: All encryption keys and credentials stored in GCP Secret Manager
* **Audit Trails**: Google Cloud Audit Logs for infrastructure-level access tracking

***

## Voice & Video Transcript PII/PHI Redaction

Live captions, call transcripts, and post-call transcripts are generated by Devotel's speech-to-text subprocessor with PII/PHI redaction enabled by default. Sensitive numerics — credit-card numbers, social-security numbers, and similar — are masked at the source, before any transcript text is stored or written to logs. For HIPAA organizations, this means PHI spoken on a call is redacted before it is persisted.

### Redaction is on by default

Transcript redaction is enabled by default and cannot be turned off from your dashboard or API. Turning it off is a deployment-wide change Devotel makes only for archival-compliance verticals (for example, legal or healthcare) that are contractually required to retain *raw*, unredacted transcripts under their own safeguards and BAA.

> **Warning:** Because this control applies to a whole deployment rather than a single organization, it cannot be scoped to one workspace. If your deployment handles PHI, redaction should stay enabled — confirm its status in writing with your Devotel contact as part of your BAA before you store any PHI.

If raw-transcript retention was ever enabled for your deployment, transcripts captured during that window were stored unredacted and are **not** masked retroactively. Review and purge them per your retention policy if they contain PHI, and ask Devotel to confirm redaction is re-enabled for all transcripts going forward.

***

## Shared Responsibility

HIPAA compliance is a shared responsibility between Devotel and the customer:

| Responsibility                                                | Devotel | Customer |
| ------------------------------------------------------------- | ------- | -------- |
| Infrastructure security                                       | ✅       |          |
| Data encryption at rest                                       | ✅       |          |
| Data encryption in transit                                    | ✅       |          |
| Access control enforcement                                    | ✅       |          |
| PHI access logging                                            | ✅       |          |
| Transcript PII/PHI redaction (default-on)                     | ✅       |          |
| Confirming transcript redaction is enabled before storing PHI |         | ✅        |
| BAA execution                                                 | ✅       | ✅        |
| Workforce training                                            |         | ✅        |
| Breach notification procedures                                | ✅       | ✅        |
| PHI minimum necessary standard                                |         | ✅        |
| Patient consent management                                    |         | ✅        |
| Risk assessment                                               | ✅       | ✅        |

***

## Incident Response

In the event of a suspected PHI breach:

1. Devotel's security team is notified within **1 hour** via automated alerting
2. Affected organizations are notified within **24 hours** per HIPAA Breach Notification Rule
3. PHI access logs are immediately preserved and exported for forensic analysis
4. Remediation steps are documented and shared with affected parties

***

*Last updated: April 2026*
*For questions about HIPAA compliance, contact: [compliance@devotel.io](mailto:compliance@devotel.io)*