Audit Events

Audit events are the core data model of the Audit Service. Every action performed on the platform -- user logins, data access, configuration changes, administrative operations -- is captured as an audit event with full context including actor, resource, state changes, and request metadata.

AuditEvent Entity

Field	Type	Description
`id`	UUID	Auto-generated event ID
`tenantId`	UUID	Tenant that owns the event
`eventType`	EventType	Categorized event type (e.g., `LOGIN`, `CREATE`, `DATA_ACCESS`)
`action`	String	Specific action performed (e.g., `user.login`, `dashboard.create`)
`actorId`	UUID	Who performed the action
`actorType`	ActorType	`USER`, `SERVICE`, `SYSTEM`, `ANONYMOUS`, or `API_KEY`
`actorEmail`	String	Human-readable actor identity
`resourceType`	String	Type of resource affected (e.g., `dashboard`, `query`)
`resourceId`	String	Identifier of the affected resource
`resourceName`	String	Human-readable resource name
`previousState`	JSON	Resource state before the change
`newState`	JSON	Resource state after the change
`ipAddress`	String	Client IP address
`userAgent`	String	Client user agent string
`correlationId`	String	Request trace correlation ID
`requestId`	String	Unique request identifier
`requestMethod`	String	HTTP method (GET, POST, etc.)
`requestPath`	String	HTTP request path
`responseStatus`	Integer	HTTP response status code
`durationMs`	Long	Request duration in milliseconds
`severity`	Severity	`DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`
`success`	Boolean	Whether the operation succeeded
`errorMessage`	String	Error details if the operation failed
`metadata`	JSON	Additional context as key-value pairs
`createdAt`	Instant	Timestamp when the event was created

Create an Audit Event (Synchronous)

Endpoint: POST /api/v1/audit/events

curl -X POST http://localhost:8086/api/v1/audit/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "eventType": "CREATE",
    "action": "dashboard.create",
    "actorId": "660e8400-e29b-41d4-a716-446655440000",
    "actorType": "USER",
    "actorEmail": "admin@acme.com",
    "resourceType": "dashboard",
    "resourceId": "dash-001",
    "resourceName": "Sales Overview",
    "severity": "INFO",
    "success": true,
    "metadata": {
      "source": "bi-workbench",
      "dashboardType": "analytical"
    }
  }'

Returns 201 Created with the full event response.

Create an Audit Event (Asynchronous)

Endpoint: POST /api/v1/audit/events/async

Queues the event via Kafka for asynchronous processing. Returns 202 Accepted immediately.

curl -X POST http://localhost:8086/api/v1/audit/events/async \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "tenantId": "550e8400-e29b-41d4-a716-446655440000",
    "eventType": "DATA_ACCESS",
    "action": "query.execute",
    "actorId": "660e8400-e29b-41d4-a716-446655440000",
    "actorType": "USER",
    "resourceType": "query",
    "resourceId": "q-12345"
  }'

Query Events

Get Event by ID

Endpoint: GET /api/v1/audit/events/:eventId

List Tenant Events (Paginated)

Endpoint: GET /api/v1/audit/tenants/:tenantId/events

Parameter	Type	Default	Description
`page`	int	0	Page number (0-based)
`size`	int	50	Page size

List Events by Time Range

Endpoint: GET /api/v1/audit/tenants/:tenantId/events/time-range

Parameter	Type	Description
`startTime`	Instant	Start time (ISO-8601)
`endTime`	Instant	End time (ISO-8601)

List Events by Actor

Endpoint: GET /api/v1/audit/tenants/:tenantId/actors/:actorId/events

List Events by Resource

Endpoint: GET /api/v1/audit/tenants/:tenantId/resources/:resourceType/:resourceId/events

Get Events by Correlation ID

Endpoint: GET /api/v1/audit/correlation/:correlationId

Returns all events that share a correlation ID, useful for tracing a request across services.

List Failed Events

Endpoint: GET /api/v1/audit/tenants/:tenantId/events/failed

Database Indexes

The audit_events table includes the following indexes for query performance:

Index	Columns	Purpose
`idx_audit_tenant_created`	`tenant_id, created_at DESC`	Tenant event listing sorted by time
`idx_audit_actor`	`actor_id`	Actor-based queries
`idx_audit_resource`	`resource_type, resource_id`	Resource-based queries
`idx_audit_correlation`	`correlation_id`	Request trace correlation

Architecture Search