Audit Event Reference

Scope

This reference defines the audit event schema used by the Audit Collector service. It covers the event structure, log types, source types, and query parameters for retrieving audit records.

Definitions

Term	Description
Audit Event	A recorded event capturing system activity for compliance and forensic analysis
Log Type	Category of the audit event (e.g., authorization decision, policy change)
Source Type	Origin of the audit event (e.g., API gateway, policy engine)
Log Entity	The payload containing the event message and additional details

Allowed Values

Log Types

Value	Description
AUTHORIZATION_DECISION	Records authorization check results
POLICY_CHANGE	Records policy creation, update, or deletion
TENANT_MEMBERSHIP	Records tenant membership changes
ROLE_ASSIGNMENT	Records role assignment or revocation

Source Types

Value	Description
API_GATEWAY	Event originated from the API gateway
POLICY_ENGINE	Event originated from the policy engine
ADMIN_CONSOLE	Event originated from administrative operations

Used By

• Decision Trace Headers
• Event Model

---

Diagram

---

Audit Event Structure

AuditEntity

The primary audit event record.

Field	Type	Description
id	String	Unique identifier for the audit event
createTime	ISO 8601 Timestamp	When the event was recorded
logType	String	Category of the event (see Log Types)
sourceType	String	Origin of the event (see Source Types)
serviceName	String	Name of the service that generated the event
logEntity	LogEntity	The event payload

LogEntity

The event payload containing message and details.

Field	Type	Description
message	String	Human-readable description of the event
details	Object	Additional contextual data as key-value pairs

---

Query Parameters

When listing audit events, the following query parameters are available:

Parameter	Type	Description
service_name	String	Filter by service name
log_type	String	Filter by log type
log_source_type	String	Filter by source type
pg_offset	Integer	Pagination offset
pg_count	Integer	Number of records to return
date_range_min	ISO 8601 Timestamp	Start of time range filter
date_range_max	ISO 8601 Timestamp	End of time range filter

---

Minimal Example

Create Audit Event Request

{
  "audit": {
    "serviceName": "policy-engine",
    "logType": "AUTHORIZATION_DECISION",
    "sourceType": "POLICY_ENGINE",
    "createTime": "2024-03-15T10:30:00Z",
    "logEntity": {
      "message": "Permission denied for resource access",
      "details": {
        "subject": "user_42",
        "resource": "doc_99",
        "action": "write",
        "decision": "deny"
      }
    }
  }
}

Create Audit Event Response

{
  "success": true,
  "error": null,
  "audit": {
    "id": "aud_a1b2c3d4",
    "serviceName": "policy-engine",
    "logType": "AUTHORIZATION_DECISION",
    "sourceType": "POLICY_ENGINE",
    "createTime": "2024-03-15T10:30:00Z",
    "logEntity": {
      "message": "Permission denied for resource access",
      "details": {
        "subject": "user_42",
        "resource": "doc_99",
        "action": "write",
        "decision": "deny"
      }
    }
  }
}

List Audits Response

{
  "success": true,
  "error": null,
  "metaData": {
    "total": 150,
    "pagination": {
      "offset": 0,
      "count": 50
    },
    "timeRange": {
      "startDate": "2024-03-01T00:00:00Z",
      "endDate": "2024-03-15T23:59:59Z"
    }
  },
  "results": [
    {
      "id": "aud_a1b2c3d4",
      "serviceName": "policy-engine",
      "logType": "AUTHORIZATION_DECISION",
      "sourceType": "POLICY_ENGINE",
      "createTime": "2024-03-15T10:30:00Z",
      "logEntity": {
        "message": "Permission denied for resource access",
        "details": {
          "subject": "user_42",
          "resource": "doc_99"
        }
      }
    }
  ]
}

---

Invalid Example

Missing required serviceName field:

{
  "audit": {
    "logType": "AUTHORIZATION_DECISION",
    "logEntity": {
      "message": "Some event"
    }
  }
}

Error Response:

{
  "success": false,
  "error": "serviceName is required",
  "audit": null
}

---

Notes

• All timestamps use ISO 8601 format with timezone
• The details field in logEntity accepts arbitrary key-value pairs for flexible event context
• Pagination defaults apply when pg_offset and pg_count are not specified
• Time range filters are inclusive on both ends

warning

Audit events are immutable once created. There is no update or delete operation for compliance integrity.

Next Step

After understanding the audit event schema, configure observability in your deployment using the Observability Overview.

Related Docs

Decision Trace Headers

Trace authorization decisions

Event Model

Platform event structure

Error Codes

Error response reference

API Overview

Platform API reference