Send AuditEvents to Auditbox

This guide describes sending your AuditEvents to Auditbox.

Authentication

Auditbox uses Keycloak for authentication and authorization, although any compliant OAuth2 identity provider (IDP) will work with proper setup. To access the FHIR API, you need to obtain a JWT access token from your IDP instance.

Getting a Token

All FHIR API requests must include an Authorization header with a Bearer token issued by the identity provider:

Authorization: Bearer [your-jwt-token]

To obtain a token from Keycloak, our default IDP, use the OAuth 2.0 client credentials or password grant flow. For example:

curl "${keycloak_url}/realms/auditbox/protocol/openid-connect/token" \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${client_id}" \
  -d "client_secret=${client_secret}" \
  -d "grant_type=client_credentials"

The JSON response will contain an access_token key that you need to use for API requests.

Creating AuditEvents

One of the main operations you'll do on Auditbox is storing AuditEvents. There are two options to upload events - single event and bulk.

Both endpoints in the end return your request, but with some changes:

• Event's meta.lastUpdated gets bumped.
• Event's id field is replaced with a new value.

Single event upload

The /AuditEvent endpoint accepts a single AuditEvent for upload to Auditbox.

curl "${auditbox_url}/AuditEvent" \
  -X POST \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer ${token}" \
  -d \
  '{
     "resourceType": "AuditEvent",
     "type": {
       "system": "http://dicom.nema.org/resources/ontology/DCM",
       "code": "110100",
       "display": "Application Activity"
     },
     "action": "E",
     "recorded": "2026-01-16T16:03:16Z",
     "outcome": "0",
     "agent": [
       {
         "requestor": true,
         "altId": "user@example.com"
       }
     ],
     "source": {
       "observer": {
         "display": "My System"
       }
     }
   }'

Upon finishing, one of those status codes may be returned:

Bulk upload

Whenever you have more than one AuditEvent you want to upload to Auditbox, it's best to do a bulk request. Instead of sending 10 requests with a single resource, you send one request with 10 resources, which is more efficient in regards to network and compute resources.

Example:

curl "${auditbox-url}/" \
  -X POST \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer ${token}" \
  -d '{
    "resourceType": "Bundle",
    "type": "collection",
    "entry": [
      {
        "resource": {
          "resourceType": "AuditEvent",
          "type": {
            "system": "http://dicom.nema.org/resources/ontology/DCM",
            "code": "110100",
            "display": "Application Activity"
          },
          "action": "E",
          "recorded": "2026-01-16T16:03:16Z",
          "outcome": "0",
          "agent": [
            {
              "requestor": true,
              "altId": "user@example.com"
            }
          ],
          "source": {
            "observer": {
              "display": "My System"
            }
          }
        }
      }
    ]
  }'