Audit API

The Rensei audit log provides a tamper-evident, cryptographically verifiable record of all security-relevant platform events. The audit API exposes event queries, Merkle root anchoring, SIEM export, inclusion proofs, and crypto-shredding for compliance workflows.

Architecture overview

Events are stored in partitioned PostgreSQL tables (monthly RANGE partitions with row-level security). Each row carries an Ed25519 signature linking it to the previous row's hash, forming a hash chain. Merkle trees are computed over event batches and optionally anchored to a trusted third-party timestamp authority (RFC 3161).

Events endpoint

Query audit events with filtering.

GET /api/audit/events
Authorization: Bearer rsk_live_<key> (or cookie session)

Query parameters

Parameter	Description
`type`	Event type filter (e.g. `webhook.ingest`, `session.started`, `policy.evaluated`)
`sessionId`	Filter by session ID
`orgId`	Filter by org (operator-admin only)
`from`	ISO 8601 start time
`to`	ISO 8601 end time
`limit`	Maximum results (default: 50, max: 500)
`cursor`	Pagination cursor

Response

{
  "events": [
    {
      "eventId": "evt_01abc...",
      "type": "session.started",
      "timestamp": "2026-06-02T12:00:00Z",
      "orgId": "org_01abc...",
      "sessionId": "sess_01abc...",
      "actorId": "user_01abc...",
      "payload": { "workType": "feature", "issueName": "Add dark mode" },
      "hash": "sha256:a1b2c3...",
      "signature": "ed25519:d4e5f6..."
    }
  ],
  "nextCursor": "cursor_abc..."
}

Decisions endpoint

Query Cedar policy evaluation decisions for compliance review.

GET /api/audit/decisions
Authorization: Bearer rsk_live_<key>

GET /api/audit/decisions/{decisionId}

Response

{
  "decisionId": "dec_01abc...",
  "timestamp": "2026-06-02T12:00:00Z",
  "principal": "agent:agent_01abc...",
  "action": "dispatch",
  "resource": "workflow:wf_01abc...",
  "decision": "permit",
  "policyIds": ["policy_01abc..."],
  "context": {}
}

Merkle root

Query the current Merkle root for a time range. Use this to verify that a set of events is covered by an anchor.

GET /api/audit/merkle-root
Authorization: Bearer rsk_live_<key>

Query parameters

Parameter	Description
`from`	ISO 8601 start time
`to`	ISO 8601 end time

Response

{
  "merkleRoot": "sha256:f1e2d3...",
  "eventCount": 1240,
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-02T00:00:00Z",
  "computedAt": "2026-06-02T12:00:00Z"
}

Anchoring

Anchor the current Merkle root to a trusted timestamp authority (RFC 3161). Anchors provide independent, third-party proof that a set of events existed at a specific time.

POST /api/audit/anchor
Authorization: Bearer rsk_live_<key>
Content-Type: application/json

{
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-02T00:00:00Z"
}

Response

{
  "anchorId": "anchor_01abc...",
  "merkleRoot": "sha256:f1e2d3...",
  "timestamp": "2026-06-02T12:00:00Z",
  "tsaResponse": "base64:...",
  "status": "anchored"
}

Inclusion proof

Prove that a specific event is included in a Merkle tree, without revealing other events. Suitable for compliance reports and external auditor requests.

GET /api/audit/inclusion-proof
Authorization: Bearer rsk_live_<key>

Query parameters

Parameter	Description
`eventId`	The event to prove inclusion for
`anchorId`	Optional anchor ID to tie the proof to a specific anchored root

Response

{
  "eventId": "evt_01abc...",
  "merkleRoot": "sha256:f1e2d3...",
  "proof": ["sha256:a1b2c3...", "sha256:d4e5f6..."],
  "leafIndex": 42,
  "valid": true
}

Verify inclusion

Independently verify an inclusion proof without Rensei systems:

POST /api/audit/verify-inclusion

Accepts the same proof structure returned by the inclusion-proof endpoint. Returns { valid: true } or { valid: false, reason: "..." }.

Crypto-shredding

Crypto-shredding permanently renders an audit event unreadable by destroying its encryption key. This is used for GDPR/privacy-law "right to erasure" compliance - the event record remains in the audit chain (preserving chain integrity) but its payload becomes permanently inaccessible.

POST /api/audit/crypto-shred
Authorization: Bearer rsk_live_<key>   (requires scope: audit:write)
Content-Type: application/json

{
  "eventId": "evt_01abc...",
  "reason": "GDPR Art. 17 erasure request ref:GDPR-2026-042"
}

Response

{
  "ok": true,
  "eventId": "evt_01abc...",
  "shredAt": "2026-06-02T12:05:00Z",
  "reason": "GDPR Art. 17 erasure request ref:GDPR-2026-042"
}

Check shred status

GET /api/audit/crypto-shred/status?eventId=evt_01abc...

Crypto-shredding is irreversible. The event payload is permanently unreadable. The chain hash and signature metadata remain intact to preserve audit chain integrity.

Retention policy

GET /api/audit/retention
PUT /api/audit/retention
Authorization: Bearer rsk_live_<key>   (operator-admin only)

Configure how long audit events are retained before automatic deletion. Default retention is 7 years for BFSI-compliant workspaces.

SIEM integration

Rensei supports streaming audit events to external SIEM destinations. Configure destinations via the admin API or the Security > Audit > SIEM dashboard page.

Supported destination types:

Splunk HTTP Event Collector (HEC)
Elastic / OpenSearch bulk ingest
Generic webhook (JSON POST, configurable headers)

CLI access

The af CLI provides audit commands for operators:

# Show attestation for a session
af audit attestation show <sessionId>

# Verify hash chain integrity
af audit chain verify --from 2026-06-01 --to 2026-06-02

JWKS for external verification

Audit events are signed with Ed25519 keys. External auditors can verify signatures without Rensei systems using the public JWKS endpoint:

GET /.well-known/audit-keys/{workspace_id}

See Audit JWKS for the full key format and verification guide.

Audit JWKS - public key endpoint for external verification
Security: Audit Trail - hash-chain architecture, TSA anchoring, crypto-shredding in depth
CLI: Audit - af audit command reference

On this page