AuditEvent — Regulatory traceability
Who read what, when, from where, with what outcome? AuditEvent answers, aligned with DICOM ATNA and IHE BPPC. The cornerstone of HIPAA and GDPR traceability on a FHIR server.
Purpose
AuditEvent logs security-relevant events of the FHIR system: read access, write, delete, authentication failure, bulk export. The structure is derived from DICOM ATNA audit, aligned with NIST 800-92 and IHE BPPC.
Three typical actors:
- agent: the user or system that acts.
- source: the system that records the event.
- entity: the object (resource) on which the action operated.
Key fields
| Field | Type | Cardinality | Role |
|---|---|---|---|
category | CodeableConcept[] | 0..* | Event category (REST, login, network...). |
code | CodeableConcept | 1..1 | Mandatory. Precise event type. |
action | code | 0..1 | C, R, U, D, E (Create, Read, Update, Delete, Execute). |
severity | code | 0..1 | emergency to debug (RFC 5424). |
occurred[x] | Period | dateTime | 0..1 | When the event happened. |
recorded | instant | 1..1 | Mandatory. When the audit was recorded. |
outcome | BackboneElement | 0..1 | Outcome (success, failure, partial). |
outcome.code | Coding | 1..1 | 0=Success, 4=Minor failure, 8=Serious failure, 12=Major failure. |
authorization | CodeableConcept[] | 0..* | Legal basis (GDPR Article 6). |
patient | Reference(Patient) | 0..1 | Patient concerned — frequent in healthcare. |
encounter | Reference(Encounter) | 0..1 | Encounter during which the event occurred. |
agent | BackboneElement[] | 1..* | Mandatory. Actor(s). |
agent.who | Reference | 1..1 | Actor identity. |
agent.requestor | boolean | 0..1 | Did this agent initiate the action? |
agent.network | BackboneElement | 0..1 | IP, hostname, URI. |
source | BackboneElement | 1..1 | Mandatory. Audit source. |
entity | BackboneElement[] | 0..* | Action target. |
entity.what | Reference | 0..1 | Concerned resource. |
entity.role | CodeableConcept | 0..1 | Role (Patient, Job, Master file...). |
JSON example
Successful read of a Patient by Dr Jones from IP 10.0.1.42:
{
"resourceType": "AuditEvent",
"id": "example",
"category": [{
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
"code": "rest",
"display": "RESTful Operation"
}]
}],
"code": {
"coding": [{
"system": "http://hl7.org/fhir/restful-interaction",
"code": "read",
"display": "read"
}]
},
"action": "R",
"severity": "informational",
"occurredDateTime": "2026-05-14T10:25:30+02:00",
"recorded": "2026-05-14T10:25:30.123Z",
"outcome": {
"code": {
"system": "http://terminology.hl7.org/CodeSystem/audit-event-outcome",
"code": "0",
"display": "Success"
}
},
"agent": [{
"type": {
"coding": [{
"system": "http://dicom.nema.org/resources/ontology/DCM",
"code": "humanuser",
"display": "human user"
}]
},
"who": { "reference": "Practitioner/dr-jones" },
"requestor": true,
"network": { "address": "10.0.1.42", "type": "2" }
}, {
"type": {
"coding": [{
"system": "http://dicom.nema.org/resources/ontology/DCM",
"code": "110150",
"display": "Application"
}]
},
"who": { "display": "Acme FHIR Server 4.5" },
"requestor": false
}],
"source": {
"site": { "display": "Hospital 1" },
"observer": { "reference": "Device/fhir-server" }
},
"entity": [{
"what": { "reference": "Patient/example" },
"role": {
"coding": [{
"system": "http://terminology.hl7.org/CodeSystem/object-role",
"code": "1",
"display": "Patient"
}]
}
}]
}Common pitfalls
- No
agent.requestor— an event MUST have at least one agent withrequestor=true(otherwise origin is ambiguous). - Auditing the audit — avoid logging AuditEvents about reading AuditEvents themselves: exponential loop.
- PHI in
entity.detail— don't inline patient data in cleartext in the audit: the audit would become an informal copy of the record. - No network info — without IP, forensic investigation is crippled.
- Outcome
successfor a 403 — access denied is a success of the security control but a functional failure. Markoutcome.code=4.
Related resources
- Provenance — who created/modified a resource (vs AuditEvent = who accessed).
- Consent — legal basis, may be referenced by
authorization. - CapabilityStatement — declares server audit capabilities.