API Reference

Auditbox provides a FHIR-compliant REST API for managing AuditEvent resources.

Base URL

All API endpoints are relative to your Auditbox server base URL:

http://localhost:3002

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 programmatically, you need to obtain a JWT access token from your IDP instance.

Getting a Token from Keycloak

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

Authorization: Bearer <your-jwt-token>

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

curl http://localhost:8888/realms/auditbox/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=auditbox" \
  -d "client_secret=super-secret" \
  -d "username=user@example.com" \
  -d "password=password"

The response will contain an access_token that you can use for API requests.

Disabling Authentication (Testing Only)

For testing purposes only, you can disable API authentication by setting:

AUDITBOX_API_AUTH_ENABLED=false

Warning: Never disable authentication in production environments.

FHIR API Endpoints

Metadata / Capability Statement

Get the server's capability statement describing supported operations and search parameters. While AuditBox is a FHIR server, it specializes on AuditLogs, thus not implementing features you may expect from Aidbox.

GET /metadata

Response: FHIR CapabilityStatement resource

Example:

curl http://localhost:3002/metadata

Create AuditEvent

Create a new AuditEvent resource.

POST /AuditEvent
Content-Type: application/fhir+json
Authorization: Bearer <token>

Request Body: FHIR AuditEvent resource

Response:

201 Created - Returns the created AuditEvent with generated ID
400 Bad Request - Validation errors in the request body
500 Internal Server Error - Server error occurred

Example:

curl http://localhost:3002/AuditEvent \
  -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"
       }
     }
   }'

Create Bundle

Create multiple AuditEvent resources in a single transaction.

POST /
Content-Type: application/fhir+json
Authorization: Bearer <token>

Request Body: FHIR Bundle resource with AuditEvent entries

Response:

201 Created - Returns a Bundle with created resources
400 Bad Request - Validation errors
500 Internal Server Error - Server error occurred

Example:

curl http://localhost:3002/ \
  -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"
            }
          }
        }
      }
    ]
  }'

Read AuditEvent

Retrieve a specific AuditEvent by ID.

GET /AuditEvent/{id}
Authorization: Bearer <token>

Path Parameters:

id - The AuditEvent resource ID

Response: FHIR AuditEvent resource

Response:

200 OK - Returns the FHIR AuditEvent resource or nothing
500 Internal Server Error - Server error occurred

Example:

curl \
  -H "Authorization: Bearer <token>" \
  http://localhost:3002/AuditEvent/23d0f0ad-3af1-4dab-93d9-9c40a01a58ec

Search AuditEvents

Search for AuditEvent resources using FHIR search parameters.

GET /AuditEvent?[parameters]
Authorization: Bearer <token>

Or using POST:

POST /AuditEvent/_search
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <token>

[parameters]

Response: FHIR Bundle containing matching AuditEvent resources

Supported Search Parameters

Auditbox supports the following FHIR search parameters for AuditEvent:

AuditEvent-Specific Parameters

Parameter	Type	Description	Example
`action`	token	Type of action performed	`?action=C`
`address`	string	Network address of the client	`?address=192.168.1.1`
`agent`	reference	Identifier of who performed the action	`?agent=Practitioner/123`
`agent-name`	string	Human-friendly name for the agent	`?agent-name=John`
`agent-role`	token	Agent role in the event	`?agent-role=110153`
`altId`	token	Alternative identifier for the agent	`?altId=user123`
`date`	date	Time when the event was recorded	`?date=2025-01-31`
`entity`	reference	Specific instance of resource	`?entity=Patient/456`
`entity-name`	string	Name of the entity	`?entity-name=John`
`entity-role`	token	What role the entity played	`?entity-role=1`
`entity-type`	token	Type of entity involved	`?entity-type=1`
`outcome`	token	Event outcome indicator	`?outcome=0`
`patient`	reference	Patient reference	`?patient=Patient/456`
`policy`	uri	Policy that authorized the event	`?policy=http://example.com/policy`
`site`	token	Logical source location	`?site=Hospital-Main`
`source`	reference	Source identity	`?source=Device/789`
`subtype`	token	More specific type/subtype	`?subtype=110101`
`type`	token	Type/identifier of event	`?type=110100`

Common FHIR Parameters

Parameter	Type	Description	Example
`_id`	token	Resource ID	`?_id=123`
`_lastUpdated`	date	Last update time	`?_lastUpdated=ge2025-01-01`
`_tag`	token	Search by tag	`?_tag=important`
`_profile`	uri	Search by profile	`?_profile=http://example.com/profile`
`_security`	token	Security labels	`?_security=restricted`
`_source`	uri	Source system	`?_source=http://example.com/system`
`_text`	string	Full-text search	`?_text=login`
`_content`	string	Content search	`?_content=patient`

Search Modifiers

Auditbox supports standard FHIR search modifiers and prefixes:

Date Prefixes

eq - Equal (default)
ne - Not equal
lt - Less than
le - Less than or equal
gt - Greater than
ge - Greater than or equal

Example:

# Events recorded after January 1, 2025
curl "http://localhost:3002/AuditEvent?date=ge2025-01-01" \
  -H "Authorization: Bearer <token>"

Token Modifiers

:not - Negation
:text - Text search in display/description

Example:

# Events that are NOT create actions
curl "http://localhost:3002/AuditEvent?action:not=C" \
  -H "Authorization: Bearer <token>"

Combining Parameters

Multiple parameters can be combined using &:

# Find all create actions for a specific patient after a date
curl "http://localhost:3002/AuditEvent?action=C&patient=Patient/456&date=ge2025-01-01" \
  -H "Authorization: Bearer <token>"

Search Examples

Example 1: Search by Action

curl "http://localhost:3002/AuditEvent?action=C" \
  -H "Authorization: Bearer <token>"

Example 2: Search by Date Range

curl "http://localhost:3002/AuditEvent?date=ge2025-01-01&date=le2025-01-31" \
  -H "Authorization: Bearer <token>"

Example 3: Search by Patient

curl "http://localhost:3002/AuditEvent?patient=Patient/456" \
  -H "Authorization: Bearer <token>"

Example 4: Search by Type and Outcome

curl "http://localhost:3002/AuditEvent?type=110100&outcome=0" \
  -H "Authorization: Bearer <token>"

Example 5: Full-Text Search

curl "http://localhost:3002/AuditEvent?_text=login" \
  -H "Authorization: Bearer <token>"

Example 6: Complex Query

curl "http://localhost:3002/AuditEvent?type=110100&action=E&date=ge2025-01-01&outcome=0&_count=50" \
  -H "Authorization: Bearer <token>"

Pagination

Search results support pagination using the _count and _offset parameters:

# Get first 10 results
curl "http://localhost:3002/AuditEvent?_count=10" \
  -H "Authorization: Bearer <token>"

# Get next 10 results
curl "http://localhost:3002/AuditEvent?_count=10&_offset=10" \
  -H "Authorization: Bearer <token>"

Search Parameters Endpoint

Get a list of all supported search parameters:

GET /SearchParameter

Example:

curl http://localhost:3002/SearchParameter

Health Check

Check if the Auditbox service is running and Elasticsearch is accessible:

GET /healthcheck

Response:

200 OK - Service is healthy
500 Internal Server Error - Service is unhealthy

Example:

curl http://localhost:3002/healthcheck

Response Format

All FHIR API responses use the application/fhir+json content type and follow FHIR JSON formatting conventions.

Success Response

{
  "resourceType": "AuditEvent",
  "id": "example-123",
  "meta": {
    "lastUpdated": "2025-01-31T16:03:16Z"
  },
  "type": {
    "system": "http://dicom.nema.org/resources/ontology/DCM",
    "code": "110100"
  },
  "action": "E",
  "recorded": "2025-01-31T16:03:16Z",
  "outcome": "0",
  "agent": [{
    "requestor": true,
    "who": {
      "identifier": {
        "value": "user@example.com"
      }
    }
  }],
  "source": {
    "observer": {
      "display": "My System"
    }
  }
}

Error Response

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "invalid",
    "diagnostics": "Validation error details here"
  }]
}

Rate Limiting

Currently, Auditbox does not implement rate limiting. However, for production deployments, it's recommended to implement rate limiting at the API gateway or load balancer level.

CORS

Cross-Origin Resource Sharing (CORS) can be enabled by setting the AUDITBOX_CORS_ORIGIN_HEADERS environment variable. When enabled, the API will respond with appropriate CORS headers for cross-origin requests.

Last updated: 2026-01-16T07:51:25Z