# Audit Service Configuration {#audit-service-configuration}


This document describes how the audit logging architecture works in MQUAD and how services are configured to send audit logs to the centralized audit-service.


## Audit Service API Endpoints {#audit-service-api-endpoints}


The audit-service provides endpoints under base path `/api/v1`:


### Health Endpoints {#health-endpoints}


| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Basic health check |
| GET | `/health/ready` | Readiness check |
| GET | `/health/live` | Liveness check |


### Audit Logs Endpoints {#audit-logs-endpoints}


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/audit/logs` | Ingest a new audit log entry |
| GET | `/audit/logs` | List audit logs with filtering/pagination |
| GET | `/audit/logs/system` | System-wide audit logs (super:admin only) |
| GET | `/audit/logs/{log_id}` | Get a specific audit log by ID |
| GET | `/audit/chain/verify` | Verify integrity of audit log chain |


### Compliance Endpoints {#compliance-endpoints}


| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/audit/compliance/gdpr/data-access/{user_id}` | GDPR data access report |
| POST | `/audit/compliance/consent` | Record/update user consent |
| GET | `/audit/compliance/consent/{user_id}` | Get all consent records for user |


### Export Endpoints {#export-endpoints}


| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/audit/export` | Export audit logs (json/csv) |


## Service Configuration {#service-configuration}


Each microservice must include `AUDIT_SERVICE_URL` in its configuration:

```python
audit_service_url: str = os.getenv("AUDIT_SERVICE_URL", "http://audit-service:8013")
```

All configured services:

| Service | Config File |
|---------|-------------|
| backend | `backend/api/core/config.py` |
| survey-service | `survey-service/api/core/config.py` |
| workspace-service | `workspace-service/api/core/config.py` |
| data-service | `data-service/api/core/config.py` |
| sync-service | `sync-service/api/core/config.py` |
| analytics-service | `analytics-service/api/core/config.py` |
| webhook-service | `webhook-service/api/core/config.py` |
| notification-service | `notification-service/api/core/config.py` |
| media-service | `media-service/api/core/config.py` |
| form-service | `form-service/api/core/config.py` |
| feature-flags-service | `feature-flags-service/api/core/config.py` |


## Middleware Implementation {#middleware-implementation}


Each service implements `AuditWriteMiddleware` that captures write operations (POST, PUT, PATCH, DELETE) and sends them to the audit-service.


### Middleware Files by Service {#middleware-files-by-service}


| Service | Middleware File |
|---------|-----------------|
| backend | `backend/api/interfaces/middlewares/audit_logs_write_middleware.py` |
| survey-service | `survey-service/api/common/audit_middleware.py` |
| workspace-service | `workspace-service/api/common/audit_middleware.py` |
| data-service | `data-service/api/common/audit_middleware.py` |
| sync-service | `sync-service/api/common/audit_middleware.py` |
| analytics-service | `analytics-service/api/common/audit_middleware.py` |
| webhook-service | `webhook-service/api/common/audit_middleware.py` |


### Endpoint Used {#endpoint-used}


All services send audit logs to: `POST http://audit-service:8013/api/v1/audit/logs`


### Middleware Behavior {#middleware-behavior}


1. Intercepts all POST, PUT, PATCH, DELETE requests
2. Extracts entity type and resource ID from the request path
3. Captures the request body (sanitized for sensitive fields)
4. Sends the audit log asynchronously to the audit-service
5. Falls back to local file logging (`/tmp/audit_logs_*.jsonl`) if the audit-service is unavailable


## Verification {#verification}


To verify audit logging is working:

1. Check that the service has `AUDIT_SERVICE_URL` configured
2. Verify the middleware is added to the FastAPI app
3. Check the audit-service logs for incoming requests
4. Query the audit logs endpoint: `GET /api/v1/audit/logs`


## Troubleshooting {#troubleshooting}



### Logs Not Appearing {#logs-not-appearing}


1. Verify `AUDIT_SERVICE_URL` is set in the service's environment
2. Check that the audit-service is running and accessible
3. Review service logs for errors connecting to audit-service
4. Check local backup logs in `/tmp/audit_logs_*.jsonl`


### Connection Errors {#connection-errors}


If "Error connecting to audit service" appears in logs:

- Verify network connectivity between services
- Check that audit-service is healthy: `GET /api/v1/health`
- Verify the correct endpoint URL is configured