Audit Collector Overview

Summary

The Audit Collector is the centralized service for capturing authorization decision events across the Keymate platform. It receives audit events from platform components (Policy Engine, Access Gateway, Permission Gateway), stores them for compliance and debugging purposes, and provides APIs for querying audit trails within configurable time ranges.

Why It Exists

Authorization systems require a complete audit trail for compliance, debugging, and security analysis. The Audit Collector solves this by providing:

Centralized event collection — A single service receives audit events from all platform components
Compliance support — Audit trails enable regulatory compliance and security audits
Time-range queries — Compliance teams can retrieve audit trails for specific time periods
Observability integration — Events can be correlated with distributed traces and metrics

Where It Fits in Keymate

The Audit Collector sits downstream from authorization components, receiving events asynchronously. It does not participate in authorization decisions — it only records them for later analysis.

Boundaries

This component covers:

Audit event ingestion via REST and gRPC APIs
Audit record storage and retrieval
Time-range queries with filtering and pagination
Log type and source type classification
Observability signal export

This component does not cover:

Authorization decisions → see Access Gateway
Policy management → see Policy Engine
Real-time alerting → see Operations — Observability
Long-term log retention → configure at infrastructure level

How It Works

Audit Event Model

Every audit record contains the following fields:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "serviceName": "policy-engine",
  "logType": "ACCESS_GRANTED",
  "sourceType": "POLICY_ENGINE",
  "createTime": "2024-01-15T10:30:00Z",
  "logEntity": {
    "message": "Access request processed",
    "details": {
      "userId": "user123",
      "resourceId": "resource456",
      "decision": "ALLOW"
    }
  }
}

Log Types

The logType field indicates the type of audit event:

LogType	Description
`ACCESS_GRANTED`	Authorization request permitted
`ACCESS_DENIED`	Authorization request denied

Source Types

The sourceType field identifies which component generated the event:

SourceType	Description
`POLICY_ENGINE`	Policy management operations
`ACCESS_GATEWAY`	API gateway authorization decisions
`PERMISSION_GATEWAY`	Application-level permission checks

Log Entity

The nested logEntity contains the event details:

Field	Type	Description
`message`	string	Human-readable event description
`details`	object	Structured event data for filtering and analysis

Time-Range Queries

Audit queries require a time range to ensure efficient retrieval. The maximum query range is configurable to prevent expensive queries on large datasets.

API Reference

REST API

Base Path: /v1/fga/audits

Create Audit

POST /v1/fga/audits

Request Body:

{
  "audit": {
    "serviceName": "policy-engine",
    "logType": "ACCESS_GRANTED",
    "sourceType": "POLICY_ENGINE",
    "createTime": "2024-01-15T10:30:00Z",
    "logEntity": {
      "message": "Access request processed",
      "details": {
        "userId": "user123",
        "decision": "ALLOW"
      }
    }
  }
}

Response (200 OK):

{
  "success": true,
  "error": null,
  "audit": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "serviceName": "policy-engine",
    "logType": "ACCESS_GRANTED",
    "sourceType": "POLICY_ENGINE",
    "createTime": "2024-01-15T10:30:00Z",
    "logEntity": { ... }
  }
}

List Audits

GET /v1/fga/audits?service_name=policy-engine&log_type=ACCESS_GRANTED&date_range_min=2024-01-10T00:00:00Z&date_range_max=2024-01-15T00:00:00Z&pg_offset=0&pg_count=20

Query Parameters:

Parameter	Type	Required	Default	Description
`date_range_min`	ISO-8601	Yes	—	Range start time
`date_range_max`	ISO-8601	Yes	—	Range end time
`service_name`	string	No	—	Filter by service
`log_type`	enum	No	—	Filter by log type
`log_source_type`	enum	No	—	Filter by source type
`pg_offset`	long	No	0	Pagination offset
`pg_count`	long	No	20	Page size (max: 100)

Response (200 OK):

{
  "success": true,
  "error": null,
  "metaData": {
    "totalRows": 150,
    "currentPagination": { "offset": 0, "count": 20 },
    "timeRange": { "startTime": "...", "endTime": "..." }
  },
  "results": [ ... ]
}

gRPC API

Method	Request	Response	Description
`CreateAudit`	`CreateAuditRequest`	`CreateAuditResponse`	Create audit record
`ListAudits`	`ListAuditsRequest`	`ListAuditsResponse`	Query audit records

Validation Rules

Field	Rule
`serviceName`	Required, non-empty
`logType`	Required, valid enum value
`sourceType`	Required, valid enum value
`createTime`	Required
`logEntity.message`	Required, non-empty
`logEntity.details`	Required
Time range	Must not exceed configured maximum

Diagram

Example Scenario

Scenario

The Policy Engine creates a new RBAC policy and sends an audit event to the Audit Collector.

Input

Actor: Policy Engine service
Resource: Audit Collector API
Action: Create audit event

Context:

{
  "serviceName": "policy-engine",
  "logType": "ACCESS_GRANTED",
  "sourceType": "POLICY_ENGINE",
  "createTime": "2024-01-15T10:30:00Z",
  "logEntity": {
    "message": "Policy created: document-editor-access",
    "details": {
      "policyId": "123",
      "policyType": "RBAC",
      "tenant": "acme-corp",
      "action": "CREATE"
    }
  }
}

Expected Outcome

Result: Audit record created with generated UUID
Why: The Audit Collector validates the event structure, stores the record, and returns the created audit with its ID for correlation

Common Misunderstandings

"The Audit Collector evaluates access requests" — The Audit Collector only stores and queries audit events. Access evaluation happens in the Access Gateway and Permission Gateway.
"Audit events are stored as JSON" — The internal storage format is optimized for efficiency. Use the REST or gRPC API for querying — direct database access is not recommended.
"I can query any date range" — Time range queries are limited to a configurable maximum to prevent expensive queries. Contact your administrator to adjust this limit if needed.

warning

Direct database queries bypass the API's query optimizations and access controls. Always use the REST or gRPC API for audit retrieval.

Design Notes / Best Practices

Use gRPC for service-to-service — gRPC provides better performance for internal services. Use REST for external integrations and debugging.
Include sufficient context — The details object should contain enough information to reconstruct the event context: user ID, resource ID, tenant, action, and outcome.
Set appropriate time ranges — When querying, use the narrowest time range possible to improve query performance.
Correlate with traces — Include trace IDs in the details object to enable end-to-end debugging from access request to audit record.

tip

Structure your details object consistently across services. Common fields like userId, tenantId, resourceId, and action enable powerful cross-service queries.

Compliance reporting for authorization decisions
Security incident investigation
Debugging access denied errors
Auditing policy changes across tenants
SIEM integration for security monitoring

Policy Engine

Sends audit events for policy changes

Access Gateway

Sends audit events for access decisions

Operations — Observability

Monitoring and alerting setup

Integrations — Telemetry

OpenTelemetry configuration

FAQ

How long are audit records retained?

Retention is managed at the infrastructure level, not by the Audit Collector. Configure retention policies based on your compliance requirements.

Can I query audits across multiple services?

Yes. Omit the service_name filter parameter to retrieve audits from all services within the specified time range.

What happens if the Audit Collector is unavailable?

Sending services should implement retry logic with exponential backoff for transient failures. Authorization decisions are not blocked by audit failures.

How do I increase the maximum query date range?

Contact your platform administrator to adjust the maximum query range configuration. Larger ranges may impact query performance.

Summary​

Why It Exists​

Where It Fits in Keymate​

Boundaries​

How It Works​

Audit Event Model​

Log Types​

Source Types​

Log Entity​

Time-Range Queries​

API Reference​

REST API​

Create Audit​

List Audits​

gRPC API​

Validation Rules​

Diagram​

Example Scenario​

Scenario​

Input​

Expected Outcome​

Common Misunderstandings​

Design Notes / Best Practices​

Related Use Cases​

Related Docs​