[auditbox] Add usage guide

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
 

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 <your-jwt-token>
-```
-
-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 <token>
 ```
@@ -87,42 +34,12 @@ Authorization: Bearer <token>
 - **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 <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
+### Upload Bundle
 
 Create multiple AuditEvent resources in a single transaction.
 
 ```http
-POST /
+POST [base]/
 Content-Type: application/fhir+json
 Authorization: Bearer <token>
 ```
@@ -134,49 +51,12 @@ Authorization: Bearer <token>
 - **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 <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.
 
 ```http
-GET /AuditEvent/{id}
+GET [base]/AuditEvent/[id]
 Authorization: Bearer <token>
 ```
 
@@ -189,26 +69,19 @@ Authorization: Bearer <token>
 - **200 OK** - Returns the FHIR AuditEvent resource or nothing
 - **500 Internal Server Error** - Server error occurred
 
-**Example:**
-```bash
-curl \
-  -H "Authorization: Bearer <token>" \
-  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 <token>
 ```
 
 Or using POST:
 
 ```http
-POST /AuditEvent/_search
+POST [base]/AuditEvent/_search
 Content-Type: application/x-www-form-urlencoded
 Authorization: Bearer <token>
 
@@ -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.