From 54cbeb6bc95df315665d006a0af8b578d91aa71d Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Fri, 16 Jan 2026 14:13:49 +0200 Subject: [PATCH 1/8] create bundle -> upload bundle --- docs-new/auditbox/docs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-new/auditbox/docs/api.md b/docs-new/auditbox/docs/api.md index 30aca9c56..55a370f7f 100644 --- a/docs-new/auditbox/docs/api.md +++ b/docs-new/auditbox/docs/api.md @@ -117,7 +117,7 @@ curl http://localhost:3002/AuditEvent \ }' ``` -### Create Bundle +### Upload Bundle Create multiple AuditEvent resources in a single transaction. From 412477a945c59081edb973cc5e51d503cff00e81 Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Fri, 16 Jan 2026 15:55:51 +0200 Subject: [PATCH 2/8] add usage guide for backend --- docs-new/auditbox/docs/SUMMARY.md | 1 + docs-new/auditbox/docs/api.md | 124 ----------- .../docs/getting-started/using-backend.md | 208 ++++++++++++++++++ 3 files changed, 209 insertions(+), 124 deletions(-) create mode 100644 docs-new/auditbox/docs/getting-started/using-backend.md diff --git a/docs-new/auditbox/docs/SUMMARY.md b/docs-new/auditbox/docs/SUMMARY.md index c8108738a..73660b9e9 100644 --- a/docs-new/auditbox/docs/SUMMARY.md +++ b/docs-new/auditbox/docs/SUMMARY.md @@ -5,6 +5,7 @@ * [Getting Started](getting-started/README.md) * [Run Auditbox Locally](getting-started/run-with-oneliner.md) * [Run Auditbox On Kubernetes](getting-started/run-k8s.md) +* [Using Auditbox Programmatically](getting-started/using-backend.md) ## Configuration diff --git a/docs-new/auditbox/docs/api.md b/docs-new/auditbox/docs/api.md index 55a370f7f..101aba511 100644 --- a/docs-new/auditbox/docs/api.md +++ b/docs-new/auditbox/docs/api.md @@ -10,46 +10,6 @@ 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: - -```http -Authorization: Bearer -``` - -To obtain a token from Keycloak, use the OAuth 2.0 client credentials -or password grant flow. For example: - -```bash -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: -```bash -AUDITBOX_API_AUTH_ENABLED=false -``` - -**Warning:** Never disable authentication in production environments. - ## FHIR API Endpoints ### Metadata / Capability Statement @@ -65,11 +25,6 @@ GET /metadata **Response:** FHIR CapabilityStatement resource -**Example:** -```bash -curl http://localhost:3002/metadata -``` - ### Create AuditEvent Create a new AuditEvent resource. @@ -87,36 +42,6 @@ Authorization: Bearer - **400 Bad Request** - Validation errors in the request body - **500 Internal Server Error** - Server error occurred -**Example:** -```bash -curl http://localhost:3002/AuditEvent \ - -H "Content-Type: application/fhir+json" \ - -H "Authorization: Bearer " \ - -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" - } - } - }' -``` - ### Upload Bundle Create multiple AuditEvent resources in a single transaction. @@ -134,43 +59,6 @@ Authorization: Bearer - **400 Bad Request** - Validation errors - **500 Internal Server Error** - Server error occurred -**Example:** -```bash -curl http://localhost:3002/ \ - -H "Content-Type: application/fhir+json" \ - -H "Authorization: Bearer " \ - -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. @@ -189,13 +77,6 @@ Authorization: Bearer - **200 OK** - Returns the FHIR AuditEvent resource or nothing - **500 Internal Server Error** - Server error occurred -**Example:** -```bash -curl \ - -H "Authorization: Bearer " \ - http://localhost:3002/AuditEvent/23d0f0ad-3af1-4dab-93d9-9c40a01a58ec -``` - ### Search AuditEvents Search for AuditEvent resources using FHIR search parameters. @@ -374,11 +255,6 @@ GET /healthcheck - **200 OK** - Service is healthy - **500 Internal Server Error** - Service is unhealthy -**Example:** -```bash -curl http://localhost:3002/healthcheck -``` - ## Response Format All FHIR API responses use the `application/fhir+json` content type and follow FHIR JSON formatting conventions. diff --git a/docs-new/auditbox/docs/getting-started/using-backend.md b/docs-new/auditbox/docs/getting-started/using-backend.md new file mode 100644 index 000000000..2c0ffacd3 --- /dev/null +++ b/docs-new/auditbox/docs/getting-started/using-backend.md @@ -0,0 +1,208 @@ +# Intro + +This guide describes using an Auditbox server programmatically. +Whenever you see *${...}* in this page, replace it mentally with +a value that applies to you. + +## 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: + +```http +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: + +```bash +curl "${keycloak_url}/realms/auditbox/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=password" \ + -d "client_id=${client_id}" \ + -d "client_secret=${client_secret}" \ + -d "username=${username}" \ + -d "password=${password}" +``` + +The JSON response will contain an `access_token` key that +you need to use for API requests. + +## Checking if server is up + +In order to use Auditbox, you need to make sure it's healthy. +For that you can use /healthcheck endpoint: +```bash +curl -v "${auditbox_url}/healthcheck" +``` + +Based on status code, there are a few options: + +| Code | Meaning | +|------|------------------------------------------------| +| 200 | Server and related infrastructure are healthy | +| 500 | Server is unhealthy | + +## Creating AuditEvents + +One of the main operations you'll do on Auditbox is storing +AuditEvents. There are two options to upload events - single resource +and bulk. + +### Single event upload + +As the title suggests, */AuditEvent* endpoint is used for uploading +a single AuditEvent to Auditbox. + +```bash +curl "${auditbox_url}/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" + } + } + }' +``` + +Upon finishing, one of those status codes may be returned: + +| Code | Meaning | +|------|--------------------------------------| +| 201 | Event has been created successfully | +| 400 | Request body is invalid | +| 500 | An internal server error has occured | + + +### 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:** + +```bash +curl "${auditbox-url}/" \ + -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" + } + } + } + } + ] + }' +``` + +## Reading AuditEvents by ID + +**Example:** +```bash +curl \ + -H "Authorization: Bearer ${token}" \ + "${auditbox_url}/AuditEvent/${id}" +``` +Unless there's an error raised from the server, you'll get a +status code 200. If there exists an event with provided ID, then +it shall be returned, or response body will be empty. + +## Response Format + +All FHIR API responses use the `application/fhir+json` content type and follow FHIR JSON formatting conventions. + +### Success Response + +```json +{ + "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 + +```json +{ + "resourceType": "OperationOutcome", + "issue": [{ + "severity": "error", + "code": "invalid", + "diagnostics": "Validation error details here" + }] +} +``` From 48225add9bcc9331aeb68bfde53f4f8ee6b6dc47 Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Mon, 19 Jan 2026 08:08:14 +0200 Subject: [PATCH 3/8] make request type explicit --- docs-new/auditbox/docs/getting-started/using-backend.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs-new/auditbox/docs/getting-started/using-backend.md b/docs-new/auditbox/docs/getting-started/using-backend.md index 2c0ffacd3..18abe82fb 100644 --- a/docs-new/auditbox/docs/getting-started/using-backend.md +++ b/docs-new/auditbox/docs/getting-started/using-backend.md @@ -25,6 +25,7 @@ client credentials or password grant flow. For example: ```bash curl "${keycloak_url}/realms/auditbox/protocol/openid-connect/token" \ + -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password" \ -d "client_id=${client_id}" \ @@ -64,6 +65,7 @@ a single AuditEvent to Auditbox. ```bash curl "${auditbox_url}/AuditEvent" \ + -X POST \ -H "Content-Type: application/fhir+json" \ -H "Authorization: Bearer ${token}" \ -d \ @@ -112,6 +114,7 @@ compute resources. ```bash curl "${auditbox-url}/" \ + -X POST \ -H "Content-Type: application/fhir+json" \ -H "Authorization: Bearer ${token}" \ -d '{ From 1dfb3e8dc415025e5458d1207b98ef40115fc666 Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Mon, 19 Jan 2026 08:28:27 +0200 Subject: [PATCH 4/8] dump --- .../auditbox/docs/getting-started/using-backend.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs-new/auditbox/docs/getting-started/using-backend.md b/docs-new/auditbox/docs/getting-started/using-backend.md index 18abe82fb..151ec3c36 100644 --- a/docs-new/auditbox/docs/getting-started/using-backend.md +++ b/docs-new/auditbox/docs/getting-started/using-backend.md @@ -55,13 +55,17 @@ Based on status code, there are a few options: ## Creating AuditEvents One of the main operations you'll do on Auditbox is storing -AuditEvents. There are two options to upload events - single resource +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 -As the title suggests, */AuditEvent* endpoint is used for uploading -a single AuditEvent to Auditbox. +*/AuditEvent* endpoint is used for uploading a single AuditEvent to +Auditbox. ```bash curl "${auditbox_url}/AuditEvent" \ From a0d05e17ca19c0ce4fc99ef1d22f6e2a7431d9ab Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Mon, 19 Jan 2026 09:51:27 +0200 Subject: [PATCH 5/8] implement feedback --- docs-new/auditbox/docs/api.md | 12 ++++++------ .../auditbox/docs/getting-started/using-backend.md | 6 ++---- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs-new/auditbox/docs/api.md b/docs-new/auditbox/docs/api.md index 101aba511..c4e7f83a9 100644 --- a/docs-new/auditbox/docs/api.md +++ b/docs-new/auditbox/docs/api.md @@ -20,7 +20,7 @@ on AuditLogs, thus not implementing features you may expect from Aidbox. ```http -GET /metadata +GET [base]/metadata ``` **Response:** FHIR CapabilityStatement resource @@ -30,7 +30,7 @@ GET /metadata Create a new AuditEvent resource. ```http -POST /AuditEvent +POST [base]/AuditEvent Content-Type: application/fhir+json Authorization: Bearer ``` @@ -47,7 +47,7 @@ Authorization: Bearer Create multiple AuditEvent resources in a single transaction. ```http -POST / +POST [base]/ Content-Type: application/fhir+json Authorization: Bearer ``` @@ -64,7 +64,7 @@ Authorization: Bearer Retrieve a specific AuditEvent by ID. ```http -GET /AuditEvent/{id} +GET [base]/AuditEvent/[id] Authorization: Bearer ``` @@ -82,14 +82,14 @@ Authorization: Bearer Search for AuditEvent resources using FHIR search parameters. ```http -GET /AuditEvent?[parameters] +GET [base]/AuditEvent?[parameters] Authorization: Bearer ``` Or using POST: ```http -POST /AuditEvent/_search +POST [base]/AuditEvent/_search Content-Type: application/x-www-form-urlencoded Authorization: Bearer diff --git a/docs-new/auditbox/docs/getting-started/using-backend.md b/docs-new/auditbox/docs/getting-started/using-backend.md index 151ec3c36..878f0ddfa 100644 --- a/docs-new/auditbox/docs/getting-started/using-backend.md +++ b/docs-new/auditbox/docs/getting-started/using-backend.md @@ -1,8 +1,6 @@ -# Intro +# Using Auditbox Programmatically This guide describes using an Auditbox server programmatically. -Whenever you see *${...}* in this page, replace it mentally with -a value that applies to you. ## Authentication @@ -17,7 +15,7 @@ All FHIR API requests must include an `Authorization` header with a Bearer token issued by the identity provider: ```http -Authorization: Bearer ${your-jwt-token} +Authorization: Bearer [your-jwt-token] ``` To obtain a token from Keycloak, our default IDP, use the OAuth 2.0 From 2b1322595be6a7f928ee15df4bc7ff74c2fe1d8b Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Mon, 19 Jan 2026 09:52:47 +0200 Subject: [PATCH 6/8] remove base url section form api reference --- docs-new/auditbox/docs/api.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs-new/auditbox/docs/api.md b/docs-new/auditbox/docs/api.md index c4e7f83a9..41a3a7ea1 100644 --- a/docs-new/auditbox/docs/api.md +++ b/docs-new/auditbox/docs/api.md @@ -2,14 +2,6 @@ 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 -``` - ## FHIR API Endpoints ### Metadata / Capability Statement From d10fba9326bf789bee245dca28577b74a1d0b291 Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Mon, 19 Jan 2026 10:55:14 +0200 Subject: [PATCH 7/8] fix title mismatch --- docs/SUMMARY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index df89dd134..abfbc8519 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -444,8 +444,8 @@ * [Social History Section (/V3)](modules/integration-toolkit/ccda-converter/sections/social-history-section-docs-v3.md) * [Vital signs section (/entries optional) (/V3)](modules/integration-toolkit/ccda-converter/sections/vital-signs-section-docs-entries-optional-docs-v3.md) * [Vital signs section (/entries required) (/V3)](modules/integration-toolkit/ccda-converter/sections/vital-signs-section-docs-entries-required-docs-v3.md) - * [Discharge Meds section (/entries optional)](modules/integration-toolkit/ccda-converter/sections/discharge-meds-section-entries-optional.md) - * [Discharge Meds section (/entries required)](modules/integration-toolkit/ccda-converter/sections/discharge-meds-section-entries-required.md) + * [Discharge Meds Section (/entries optional)](modules/integration-toolkit/ccda-converter/sections/discharge-meds-section-entries-optional.md) + * [Discharge Meds Section (/entries required)](modules/integration-toolkit/ccda-converter/sections/discharge-meds-section-entries-required.md) * [How to deploy the service](modules/integration-toolkit/ccda-converter/how-to-deploy-the-service.md) * [Producing C-CDA documents](modules/integration-toolkit/ccda-converter/producing-c-cda-documents.md) * [How to customize conversion rules](modules/integration-toolkit/ccda-converter/how-to-customize-conversion-rules.md) From b4e76f50eae9601c0fea07caf3995df861f8745c Mon Sep 17 00:00:00 2001 From: German Bichkovich Date: Mon, 19 Jan 2026 11:34:46 +0200 Subject: [PATCH 8/8] fix grant_type in example of getting keycloak token --- docs-new/auditbox/docs/getting-started/using-backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-new/auditbox/docs/getting-started/using-backend.md b/docs-new/auditbox/docs/getting-started/using-backend.md index 878f0ddfa..8fa6f01b5 100644 --- a/docs-new/auditbox/docs/getting-started/using-backend.md +++ b/docs-new/auditbox/docs/getting-started/using-backend.md @@ -25,7 +25,7 @@ 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 "grant_type=password" \ + -d "grant_type=client_credentials" \ -d "client_id=${client_id}" \ -d "client_secret=${client_secret}" \ -d "username=${username}" \