SapixDBSapixDB/Docs
Early Access
Phase 4 · HIPAA

HIPAA Compliance

SapixDB is HIPAA-compliant by architecture. Every write is append-only and signed, giving you an immutable, tamper-evident audit trail with zero extra tooling. The HIPAA package adds PHI field classification, access logging, and one-call audit reports.

✓ Architecture-level complianceThe audit trail requirement is satisfied automatically for every nucleotide ever written. You never need to enable it — it cannot be disabled.

How it works

1
Classify PHI fields
Tell SapixDB which payload field names contain Protected Health Information. You can do this manually via the API, or rely on the 40 well-known HIPAA identifiers that are auto-detected.
2
Access events are logged automatically
Every time a record containing a PHI field is read, SapixDB logs an access event with the accessor identity, timestamp, and which PHI fields were touched.
3
Generate audit reports on demand
Call GET /v1/hipaa/audit-report to get a timestamped report that scans the entire strand, counts PHI records, and summarizes access events. Submit it directly to a compliance auditor.

Auto-detected PHI field names

SapixDB automatically treats any payload field whose name matches one of these as PHI — no configuration required. Field name matching is case-insensitive and exact.

namepatient_namefull_namefirst_namelast_namedobdate_of_birthaddressstreet_addresszip_codephonephone_numberemailemail_addressssnsocial_security_numbermrnmedical_record_numberaccount_numberhealth_plan_numberdiagnosisdiagnosis_codeicd_codemedicationprescriptiontreatmentinsurance_idpatient_idip_addressbiometric_id

HTTP API

List PHI fields

GET /v1/hipaa/phi-fields
{
  "fields": [
    { "field_name": "ssn",         "source": "auto",   "added_at_ms": 0,             "added_by": "hipaa-spec" },
    { "field_name": "patient_notes","source": "manual", "added_at_ms": 1716400000000, "added_by": "admin" }
  ],
  "well_known_count": 40
}

Classify a custom field as PHI

POST /v1/hipaa/phi-fields
{ "field_name": "patient_notes", "added_by": "admin" }

Remove a manual classification

DELETE /v1/hipaa/phi-fields/patient_notes
// 204 No Content on success
// 400 Bad Request if field is a well-known auto-detected identifier

PHI access log

GET /v1/hipaa/access-log
{
  "events": [
    {
      "record_id": "a1b2c3d4-...",
      "phi_fields_accessed": ["ssn", "dob"],
      "timestamp_ms": 1716400060000,
      "accessor": "orders-agent"
    }
  ],
  "total": 1
}

Audit report

GET /v1/hipaa/audit-report
{
  "generated_at_ms": 1716400120000,
  "agent_id": "patient-agent",
  "summary": {
    "total_phi_fields": 42,
    "manual_phi_fields": 2,
    "well_known_phi_fields": 40,
    "total_phi_accesses": 17,
    "encrypted_blobs": 4,
    "strand_records_scanned": 3840,
    "records_with_phi": 312
  },
  "phi_fields": [ ... ],
  "recent_phi_accesses": [ ... ],
  "phi_record_ids": [ "a1b2...", "c3d4..." ]
}

Python

installation
pip install sapixdb-hipaa
classify fields + audit
import asyncio
from sapixdb_hipaa import HipaaClient

async def main():
    async with HipaaClient("http://localhost:7475") as hipaa:
        # Add custom PHI fields for your domain
        await hipaa.classify_fields(
            ["patient_notes", "insurance_group", "referring_physician"],
            added_by="[email protected]",
        )

        # Check latest access events
        log = await hipaa.get_access_log()
        print(f"{log.total} PHI access events on record")

        # Generate audit report for submission
        report = await hipaa.audit_report()
        print(f"Agent:              {report.agent_id}")
        print(f"Records scanned:    {report.summary.strand_records_scanned:,}")
        print(f"Records with PHI:   {report.summary.records_with_phi:,}")
        print(f"PHI accesses:       {report.summary.total_phi_accesses:,}")
        print(f"Encrypted blobs:    {report.summary.encrypted_blobs}")

asyncio.run(main())

HipaaClient API

MethodDescription
list_phi_fields()Return all PHI fields — auto-detected + manual.
add_phi_field(name, added_by)Manually classify a field name as PHI.
remove_phi_field(name)Remove a manual classification.
classify_fields(names, added_by)Bulk-classify multiple field names.
get_access_log()Return all PHI access events, newest first.
audit_report()Generate a full HIPAA audit report.
is_compliant()Quick signal: True if PHI classifications are in place.
⚠ Encryption key managementPHI blob encryption (AES-256-GCM) uses an external KMS — SapixDB stores the encrypted ciphertext and the key ID only. Set SAPIX_KMS_URL to connect your key management service. Without it, blobs are stored unencrypted and theencrypted_blobs counter stays at 0.
Building for SOX as well?

SapixDB has a dedicated SOX package with financial agent designation and dual-admin sign-off enforcement.