Audit Trail Guide

Kaiten maintains an append-only audit trail for entitlement and feature flag operations per instance.

What's Tracked

Event	Status	Description
`kaiten.v1.entitlement.value.get`	`ACCEPTED`	An entitlement value was read
`kaiten.v1.entitlement.usage.report.accepted`	`ACCEPTED`	Usage report was accepted
`kaiten.v1.entitlement.usage.report.rejected`	`REJECTED`	Usage report was rejected (threshold exceeded)
`kaiten.v1.feature_flag.evaluate`	`ACCEPTED`	Feature flag was evaluated

Querying the Audit Trail

GET /api/instances/{instanceSlug}/audit-trails

Query Parameters

Parameter	Type	Description
`event_name`	string	Filter by event name
`after`	RFC3339	Start of time range
`before`	RFC3339	End of time range
`limit`	integer (1-200)	Results per page
`offset`	integer	Pagination offset

Example

curl "http://localhost:6000/api/instances/acme-production/audit-trails?event_name=kaiten.v1.entitlement.usage.report.accepted&limit=10" \
  -H "Authorization: Bearer ksh_xxx"

Use Cases

Compliance auditing — prove what entitlements were checked and when
Usage debugging — identify why a usage limit was hit
Feature flag debugging — see how flags were evaluated for a specific instance
Billing verification — cross-reference usage reports with your billing system

The audit trail is a read-side log (per instance), while domain events are a write-side pipeline (per organization). Use audit trails for instance-level forensics; use webhooks for real-time integration.

Audit Trail