> ## 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 tenant BAA attestation checklist — first run

> A five-step first-run checklist for HIPAA tenants: declare PHI in scope, execute the BAA, verify the gate, read the audit log, and understand the decline and revert paths.

# HIPAA tenant BAA attestation checklist — first run

Run this checklist once when your organization first handles Protected Health Information (PHI) in Orbit. It covers only the Business Associate Agreement (BAA) attestation and gate-verification steps; the broader HIPAA enablement sequence (roles, retention, PHI-adjacent audiences, evidence binder) lives in the [HIPAA first-enablement runbook](/guides/hipaa-first-enablement).

<Warning>
  This is a **tenant-owned control**. You decide whether PHI is in scope and an owner executes the BAA. Orbit supplies the e-sign pipeline and the send-time gate, but the legal determination is yours.
</Warning>

***

## Step 1 — Declare PHI in scope

An owner or admin attests that PHI is entering the workspace. This is the act that raises the `hipaa_required` flag and opens the BAA execution flow.

* **Dashboard:** **Settings → Compliance → BAA → Start handling PHI**
* **API:** `POST /api/v1/compliance/baa/require`

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/require" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Patient appointment reminders contain PHI" }'
```

After this call:

* `baa_status` is `pending`
* `hipaa_required` is `true`
* The audit log receives a `compliance.baa.hipaa_required` entry naming the actor and the optional reason

The optional `reason` field (up to 500 characters) is recorded on the audit row.

***

## Step 2 — Execute the BAA

Execution binds the organization, so it is **owner-only**. The signer reviews the rendered template, then types their legal name into `typed_attestation`; the server rejects the call unless it matches `signer_name` exactly.

* **Dashboard:** **Settings → Compliance → BAA → Execute BAA**
* **API:** `POST /api/v1/compliance/baa/execute`

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/execute" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "Jane Roe",
    "signer_email": "jane@example.com",
    "typed_attestation": "Jane Roe"
  }'
```

On success:

* `baa_status` becomes `executed`
* `baa_executed_at`, `expires_at`, and `days_until_expiry` are populated
* The audit log receives a `compliance.baa.executed` entry carrying the signer, template version, and signature method (`type_the_name`)

That audit entry is the proof record. The stored executed PDF is available from `GET /api/v1/compliance/baa/download` for 24 hours per request.

***

## Step 3 — Verify the gate before sign-off

Before you call the first production PHI send official, prove the gate behaves. With the BAA still pending, a PHI-enabled send must return `422 HIPAA_BAA_REQUIRED`. After execution, the same send must pass.

1. **Before execution** (or on a scratch workspace left at `pending`), attempt a PHI-bearing send:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/messages" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550101",
    "channel": "sms",
    "body": "Your appointment is confirmed."
  }'
```

Expected:

```json theme={null}
{
  "error": {
    "code": "HIPAA_BAA_REQUIRED",
    "status": 422,
    "message": "Business Associate Agreement required before sending PHI traffic.",
    "details": { "reason": "pending" }
  }
}
```

2. **After execution**, repeat the same send. It should proceed past the gate and return a normal send response.

The block lands before wallet hold, quota increment, or provider dispatch, so the rejected test send costs nothing. Do not skip this verification: the gate is fail-closed, and a passing send is the only proof the workspace is ready.

***

## Step 4 — Find the audit log entries

Every BAA lifecycle action appends a row under **Settings → Audit log**. Look for these actions:

| Audit action | What it proves |
| - | - |
| `compliance.baa.hipaa_required` | An owner or admin declared PHI in scope. |
| `compliance.baa.executed` | An owner executed the BAA — this is the proof record. |
| `compliance.baa.declined` | An owner or admin attested that PHI is no longer in scope. |
| `compliance.baa.reverted` | An owner returned an executed or expired BAA to the platform default. |

The audit row, not the current status field, is the legal evidence of attestation. Keep the audit log reachable for compliance reviews.

***

## Step 5 — Know the decline and revert paths

Two paths return the workspace to the default `not_required` state. They are not interchangeable.

### Decline (`compliance.baa.declined`)

Use this when PHI was declared in scope but the organization has not yet executed the BAA and now attests that no PHI is in scope.

* **Who:** owner or admin
* **API:** `POST /api/v1/compliance/baa/decline`
* **When it fires:** from `pending` only; it refuses an executed BAA with `400`
* **Effect:** clears `hipaa_required`, returns `baa_status` to `not_required`, and lifts the send gate

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/decline" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "No PHI in scope; rolling back the attestation." }'
```

### Revert (`compliance.baa.reverted`)

Use this after an executed or expired BAA has run its contractual course and HIPAA mode has been disabled.

* **Who:** owner only
* **API:** `POST /api/v1/compliance/baa/revert`
* **When it fires:** from `executed` or `expired` only; requires HIPAA mode to be off first
* **Effect:** returns `baa_status` to `not_required` while preserving the executed PDF and audit history

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/revert" \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Organization no longer processes PHI." }'
```

If you try to revert while HIPAA mode is still enabled, the call returns `400` with a message asking you to disable HIPAA mode first.

***

## Fail-closed rule

The BAA gate is **fail-closed**. There is no bypass, tenant override, or support path that opens it while the required proof is missing. An unverifiable compliance state blocks sends rather than risk a PHI transmission. Treat any `500 HIPAA_BAA_GATE_DB_FAIL` response as a verification outage, not a missing BAA, and retry.

***

## Related pages

* [Business Associate Agreement (BAA) flow](/compliance/baa) — full lifecycle, states, and endpoints
* [HIPAA BAA gate evaluation guide](/compliance/baa-gate-guide) — how the gate evaluates a send
* [HIPAA first-enablement runbook](/guides/hipaa-first-enablement) — roles, retention, PHI audiences, and evidence binder
* [HIPAA readiness checklist runbook](/compliance/hipaa-checklist-runbook) — from the free checklist tool to go/no-go


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.