Audit log

Pre-beta · last updated 2026-06-01

Immutable by designAudit events are append-only and hash-chained. Once written, an event cannot be modified or deleted — even by workspace admins. This is intentional: the audit trail exists to satisfy compliance requirements that demand tamper-evident evidence.

Audit log overview

Every significant action in a Cendriix workspace emits a structured audit event. Events are stored in an append-only ledger where each event references the cryptographic hash of the previous event — creating a verifiable chain of custody across the entire history of a workspace.

The audit log is queryable via the API and exportable in JSON and CSV formats, making it suitable for SOC 2 evidence packages, change-management review, and incident post-mortems.

Event types

Event type	Emitted when
`run.created`	A new run is started
`run.step.started`	A workflow step begins execution
`run.step.completed`	A workflow step completes successfully
`run.step.failed`	A workflow step fails
`run.approval.requested`	An approval gate is reached and pauses
`run.approval.granted`	A gated step is approved by a human
`run.approval.rejected`	A gated step is rejected
`run.cancelled`	A run is cancelled by a user or policy
`a2a.handoff`	An agent hands off context to another agent
`cortex.entity.read`	An entity is read from the knowledge graph
`cortex.entity.written`	An entity is written to the knowledge graph
`policy.violation`	An action is blocked by a policy guardrail
`user.login`	A user authenticates
`rbac.role.changed`	A user's role is modified

Querying the audit log

bash

# List recent audit events for a workspace
curl "https://api.cendriix.ai/v1/audit?limit=50&order=desc" \
  -H "Authorization: Bearer <token>"

# Filter by run ID
curl "https://api.cendriix.ai/v1/audit?run_id=run_a1b2c3d4" \
  -H "Authorization: Bearer <token>"

# Filter by event type
curl "https://api.cendriix.ai/v1/audit?event_type=run.approval.granted&since=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer <token>"

Each event in the response includes:

event_id — unique identifier for this event
timestamp — ISO 8601 UTC timestamp
event_type — one of the types above
actor — user or agent that caused the event
payload — event-specific data (run ID, entity, action taken)
hash — SHA-256 hash of this event
prev_hash — SHA-256 hash of the preceding event (chain anchor)

Export

bash

# Export a run's full audit bundle (JSON)
curl "https://api.cendriix.ai/v1/audit/export?run_id=run_a1b2c3d4&format=json" \
  -H "Authorization: Bearer <token>" \
  -o audit-bundle.json

# Export a date range (CSV, useful for SOC 2 evidence)
curl "https://api.cendriix.ai/v1/audit/export?since=2026-01-01&until=2026-06-30&format=csv" \
  -H "Authorization: Bearer <token>" \
  -o audit-q1-q2.csv

Hash-chain integrity

You can verify the integrity of an exported audit bundle using the Cendriix CLI (when available) or by re-computing the chain manually:

bash

# Verify audit bundle integrity (CLI, when available)
cendriix audit verify --file audit-bundle.json
# ✓ Chain intact: 1,247 events, no tampering detected

Each event's hash is computed as SHA256(event_id + timestamp + event_type + payload + prev_hash). An auditor can independently verify any event by re-computing the hash and comparing it to the stored value.