Audit Trail
Every data change is logged — who did what, when, from where — immutable and retained for 6 years.
What Gets Logged
Every time data is created, modified, or deleted in the platform, the audit trail records:
| Field | What It Captures |
|---|---|
| Who | The user who performed the action |
| What | The type of record affected (patient, appointment, form, etc.) and which specific record |
| When | Exact timestamp in UTC |
| How | The action taken (create, update, delete) |
| Where | The client's IP address |
| Result | Whether the action succeeded or failed (including the HTTP status code) |
Failed actions are also logged. Unauthorized access attempts (permission denied, authentication failures) are captured and available for security review. This is critical for detecting suspicious activity.
What is NOT logged
Read-only operations (viewing records) are not logged by default. This keeps the audit trail focused on mutations and manageable in size.
Exception: break-glass sessions log every read. When a platform staff member elevates access to identifiable patient data at a specific clinic — to investigate a support ticket, respond to a security incident, or route a misdirected DSAR — every action they take inside that elevated session is logged, including reads. This is what makes break-glass defensible: the clinic gets an email and an in-app banner the moment a session opens, and the audit trail records every record they looked at, not just the ones they changed. See How Patient Data Is Protected for the full break-glass model.
Tamper-Proof
The audit log is append-only. Once an entry is written:
- It cannot be modified — no one can change what was recorded
- It cannot be deleted — no one can erase evidence of an action
- This is enforced at the database level — not just application rules, but database-level policies that reject update and delete operations
This means the audit trail can be trusted as an accurate historical record, even if the application or its administrators are compromised.
Retention
Audit records are retained for a minimum of 6 years, as required by HIPAA regulations:
| Period | Where It's Stored | Queryable? |
|---|---|---|
| 0-12 months | Primary database | Yes — searchable through admin dashboard |
| 12 months - 6 years | Archived to secure cloud storage | On request — downloadable for investigations |
| After 6 years | Deleted | No longer retained |
Special cases:
- Break-glass session records are never deleted — they are the audit trail for every elevated access by platform staff
- GDPR-related operation records are retained for 7 years
- Key rotation events are retained permanently
Sensitive Data Masking
Before writing to the audit log, sensitive information is automatically masked:
- Passwords are recorded as
[REDACTED] - API keys and tokens are recorded as
[REDACTED] - The audit trail captures what changed (field name, old value, new value) but masks sensitive values
This ensures the audit trail is useful for investigations without becoming a security liability itself.
How Clinics Use the Audit Trail
Admin dashboard
Clinic admins can search and filter audit logs by:
- Date range
- User (who performed the action)
- Record type (patient, appointment, form)
- Action type (create, update, delete)
Export
Audit logs can be exported as CSV files for external review, regulatory submissions, or legal proceedings.
Monitoring
The platform monitors the audit trail for suspicious patterns:
- Unusual numbers of failed access attempts
- Mass data access (many records in a short time)
- Access from unexpected locations
- Break-glass sessions flagged for mandatory review within 24 hours, with the clinic admin notified by email and in-app banner the moment each session opens
For developers
Technical details — audit middleware implementation, database schema, archival jobs, Telemetry forwarding, and ClickHouse integration — are available in the Audit feature spec and Audit Compliance reference.