Audit and Logging

Audit logging is essential in healthcare systems because it:

• Protects Patient Privacy: Tracks who accessed sensitive medical records, ensuring compliance with privacy laws like HIPAA
• Prevents Data Breaches: Helps detect and investigate unauthorized access to patient data
• Ensures Accountability: Records all changes to medical records, creating a clear trail of who modified what and when
• Supports Legal Requirements: Provides evidence for compliance audits and legal investigations

Aidbox provides comprehensive audit and logging capabilities:

• FHIR Basic Audit Logging Profile (BALP) implementation
• FHIR Resource versioning
• Logging configuration

FHIR Basic Audit Logging Profile (BALP) implementation

Aidbox supports the FHIR BALP Implementation Guide.

Audit events topic

Aidbox publishes audit events to a built-in AidboxSubscriptionTopic:

http://health-samurai.io/fhir/core/StructureDefinition/AuditEventsR4BALP

Each event is a FHIR R4 AuditEvent resource. To receive events, create an AidboxTopicDestination with this URL in the topic element. Any destination kind works: webhook, Kafka, GCP Pub/Sub, and the others listed in supported channels.

How the topic behaves:

• Destinations switch audit logging on. With no destination on the topic, Aidbox builds no audit events and requests carry no audit overhead. Delete the last destination to stop audit logging.
• The topic is part of Aidbox. You do not create an AidboxSubscriptionTopic resource for it, and Aidbox rejects a stored topic that reuses its URL with 422.
• Every destination receives its own copy of each event. Delivery guarantees, batching, and retries come from the destination kind.
• Aidbox publishes events produced from the moment a destination exists. A new destination receives no earlier events.
• With organization-based hierarchical access control, the AuditEvent meta carries the organization of the request.

For a step-by-step setup, see How to subscribe to audit events.

Aidbox as a source of audit events

Aidbox produces audit events for significant events:

• FHIR CRUD & Search operations for basic FHIR resources and custom resources (with BALP profiles)
• FHIR CRUD & Search operations for Patient compartment resources (with Patient-specific BALP profiles)
• User login and logout events (custom Aidbox event types, not BALP-conformant)
• Password change events (DICOM subtype 110139)
• SQL operations via $psql/$sql (custom aidbox/sql-interaction type, not BALP-conformant)
• Bundle transaction entries (each entry audited individually with BALP profiles)

BALP profile selection

Aidbox assigns a BALP profile to each AuditEvent based on the operation type and whether the operation involves a Patient.

When Patient-specific profiles are used:

• The resource is a Patient — CRUD operations directly on the Patient resource (e.g. PUT /fhir/Patient/123)
• The resource is in the Patient Compartment and references a Patient (e.g. creating an Observation with subject pointing to a Patient)

Example: AuditEvent for Patient update

When you update a Patient resource, the generated AuditEvent uses the IHE.BasicAudit.PatientUpdate profile:

{
  "resourceType": "AuditEvent",
  "meta": {
    "profile": [
      "https://profiles.ihe.net/ITI/BALP/StructureDefinition/IHE.BasicAudit.PatientUpdate"
    ]
  },
  "type": {
    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
    "code": "rest",
    "display": "Restful Operation"
  },
  "subtype": [
    {
      "system": "http://hl7.org/fhir/restful-interaction",
      "code": "update",
      "display": "update"
    }
  ],
  "action": "U",
  "recorded": "2026-02-25T12:00:00Z",
  "outcome": "0",
  "agent": [
    {
      "who": {
        "reference": "Client/my-client"
      },
      "requestor": true
    }
  ],
  "source": {
    "observer": {
      "display": "Aidbox"
    }
  },
  "entity": [
    {
      "what": {
        "reference": "Patient/example"
      },
      "role": {
        "system": "http://terminology.hl7.org/CodeSystem/object-role",
        "code": "4",
        "display": "Domain Resource"
      },
      "type": {
        "system": "http://terminology.hl7.org/CodeSystem/audit-entity-type",
        "code": "2",
        "display": "System Object"
      }
    }
  ]
}

Password change AuditEvent

When a user's password is changed (via PUT /User/:id or PATCH /User/:id), Aidbox generates an AuditEvent with DICOM subtype 110139 ("User password changed").

{
  "resourceType": "AuditEvent",
  "type": {
    "system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
    "code": "rest",
    "display": "Restful Operation"
  },
  "subtype": [
    {
      "system": "http://dicom.nema.org/resources/ontology/DCM",
      "code": "110139",
      "display": "User password changed"
    }
  ],
  "action": "U",
  "outcome": "0",
  "entity": [
    {
      "what": { "reference": "User/example-user" },
      "type": {
        "system": "http://terminology.hl7.org/CodeSystem/audit-entity-type",
        "code": "2"
      },
      "role": {
        "system": "http://terminology.hl7.org/CodeSystem/object-role",
        "code": "4"
      }
    }
  ],
  "agent": [
    {
      "who": { "identifier": { "value": "root" } },
      "requestor": true
    },
    {
      "who": { "display": "Aidbox" },
      "requestor": false
    }
  ]
}

Aidbox generates this event regardless of whether the password value changed.

External Audit record repository support

To send audit events to an external Audit record repository, create a webhook AidboxTopicDestination on the audit events topic with the repository endpoint. Aidbox delivers events as a FHIR Bundle of type history, described in Notification shape. The first entry of the bundle is an AidboxSubscriptionStatus, so check that the repository accepts this shape.

For setup instructions and a payload example, see How to subscribe to audit events.

FHIR Resource versioning

A separate version is recorded in the history table each time a resource is created, updated, or deleted.

All versions can be accessed using the _history operation.

Logging configuration

Aidbox automatically logs all auth, API, database, and network events, so in most cases, basic audit logs may be derived from Aidbox logs.

Aidbox also provides ways to extend Aidbox logs.

Audit coverage

Known limitations

See also: