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 30aca9c56..41a3a7ea1 100644 --- a/docs-new/auditbox/docs/api.md +++ b/docs-new/auditbox/docs/api.md @@ -2,54 +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 -``` - -## 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 @@ -60,22 +12,17 @@ on AuditLogs, thus not implementing features you may expect from Aidbox. ```http -GET /metadata +GET [base]/metadata ``` **Response:** FHIR CapabilityStatement resource -**Example:** -```bash -curl http://localhost:3002/metadata -``` - ### Create AuditEvent Create a new AuditEvent resource. ```http -POST /AuditEvent +POST [base]/AuditEvent Content-Type: application/fhir+json Authorization: Bearer ``` @@ -87,42 +34,12 @@ 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" - } - } - }' -``` - -### Create Bundle +### Upload Bundle Create multiple AuditEvent resources in a single transaction. ```http -POST / +POST [base]/ Content-Type: application/fhir+json Authorization: Bearer ``` @@ -134,49 +51,12 @@ 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. ```http -GET /AuditEvent/{id} +GET [base]/AuditEvent/[id] Authorization: Bearer ``` @@ -189,26 +69,19 @@ 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. ```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 @@ -374,11 +247,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..8fa6f01b5 --- /dev/null +++ b/docs-new/auditbox/docs/getting-started/using-backend.md @@ -0,0 +1,213 @@ +# Using Auditbox Programmatically + +This guide describes using an Auditbox server programmatically. + +## 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" \ + -X POST \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "grant_type=client_credentials" \ + -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 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 + +*/AuditEvent* endpoint is used for uploading a single AuditEvent to +Auditbox. + +```bash +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: + +| 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}/" \ + -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" + } + } + } + } + ] + }' +``` + +## 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" + }] +} +``` 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)