The Audit ledger

The Audit ledger is the record of every governed action and lifecycle change. It is designed so tampering is detectable.

What makes it tamper-evident

• Append-only. Update and delete are revoked from the application's database roles. Entries can only be added.
• Hash-chained per tenant. The database computes each entry's hash from the previous entry's hash, under a per-tenant lock. Changing or removing an old entry breaks every hash after it.
• Verifiable on demand. The database's own verification function is the only verifier; the API reports its result.
• Masked. Sensitive text is masked before it is written.

Each state-changing call writes an entry in the same transaction as the change, carrying the actor, the resource, who owned the resource at that moment, the platform and workspace, the result, and the request ID.

Verify the chain

curl "https://$BAIRAV_HOST/api/ledger/verify" \
  -H "Authorization: Bearer $BAIRAV_ACCESS_TOKEN"

The response reports the first break, if any, with a reason for each entry. Verifying needs the view_ledger permission.

Detect truncation: record the head

A hash chain proves entries were not altered; it cannot prove the newest entries were not cut off unless you remember where the chain ended. Record the head somewhere outside Bairav:

curl "https://$BAIRAV_HOST/api/ledger/head" -H "Authorization: Bearer $BAIRAV_ACCESS_TOKEN"

Later, pass it back:

curl "https://$BAIRAV_HOST/api/ledger/verify?expected_head=$HEAD" -H "Authorization: Bearer $BAIRAV_ACCESS_TOKEN"

Read and export

Call	Needs	Notes
GET /api/ledger	view_ledger	Lists entries
GET /api/ledger/agent-actions	view_ledger	One row per governed agent action
GET /api/ledger/export.csv	export_audit	At most 50,000 rows

Correlate with your own systems

Every Portal API response carries an X-Request-ID header. Send your own value in the request and it is echoed back and stamped into the ledger entries that request writes. That gives you a join key between your logs and the Audit ledger.