Audit Trail

Talonic records every meaningful access and lifecycle event on your documents in a server-side, append-only audit trail. Events are chained together with cryptographic hashes per workspace, so tampering is detectable, and audit history survives the destruction of the records it describes. Audit events are emitted by the server, not the browser: an API call that touches a document produces the same audit event as a click in the UI, so there is no way to read or change a record without leaving a trace.

Recorded events

Parameter	Type	Description
document.viewed	access	A document is opened and its content read.
document.downloaded	access	A document's original file is downloaded.
document.exported	access	A document is exported.
document.deleted	lifecycle	A document is deleted (a soft delete when archive mode is on).
document.disposed	lifecycle	Content is destroyed through the disposition workflow.
retention.*	records	Policy created, updated, or deleted; assignments added or removed; expiry dates computed (retention.set).
disposition.*	records	Documents entering the review queue (disposition.pending) and approvals (disposition.approved).
hold.*	records	Holds applied, released, and superadmin overrides (hold.applied, hold.released, hold.override_released).
archive.settings_changed	settings	Archive mode, step-up requirement, or storage quota changed.
tenant.deletion_blocked_by_hold	enforcement	A workspace deletion refused because active holds exist.
fixity.*	integrity	Fixity verification: per-document mismatches (with quarantine), completed verification cycles, and orphan reports.
audit.anchored	integrity	A daily chain-head anchor written to external storage.
erasure.* / export.*	workflows	Erasure request lifecycle (requested, located, approved, rejected, executed) and tenant export jobs (requested, completed, failed).
compartment.* / scim.* / auth.*	access	Compartment changes, SCIM provisioning and token lifecycle, MFA enrollment and disablement, failed step-up attempts.

Each event records when it happened (a server-side timestamp), who acted, what entity the event concerns (type, ID, and a display label), why (a reason field where the action carries one, for example a hold release reason), and request context. Actors are identified by type and identity: user (a person, with their user ID and label), api_key (a machine integration, with the specific key's identity), system (Talonic itself, for example the retention engine), or superadmin (platform-level administrative action). API-key attribution matters in practice: when an integration reads or exports documents, the trail shows exactly which key did it, not a generic API entry.

Tamper evidence: the per-workspace hash chain

Recording events is not enough for an archive; you also need to show they have not been altered after the fact. When an event is written, Talonic computes a SHA-256 fingerprint of the event's contents, and the calculation includes the fingerprint of the previous event in that workspace's log. Each event therefore carries two values: its own event_hash and the prev_hash of its predecessor. Every event's fingerprint depends on the entire history before it: if anyone edits, deletes, or inserts a past event, verification fails at exactly the first altered event. Events are written in a strictly serialized order per workspace, so the chain is linear and unambiguous.

What this gives you: the ability to demonstrate to an auditor that the log you present is the log that was written, in the order it was written. What it does not do: it is not access control (that is handled separately by tenant isolation and roles). Tamper evidence makes alteration detectable, not impossible. Verification is self-serve: the verify endpoint walks the chain from the start and reports either a fully valid chain or the exact first broken event.

An in-database chain alone has a known limit: an attacker with full database write access could rewrite an entire chain consistently. To close that gap, Talonic anchors each workspace's chain daily: a small record containing the latest event ID and the chain head hash (linked to the previous anchor) is written to external object storage, outside the database. Verification then checks both directions: the chain walk catches an inconsistent tamper, and the anchor cross-check catches a consistent full-chain rewrite, because a rewritten chain no longer matches the anchored heads. Today anchors are stored in the encrypted, versioned object store with application-level write-once protection; anchoring to storage-level WORM (S3 Object Lock) follows the archive storage rollout and is on the roadmap.

Verify chain integrity and anchors

curl "$API_URL/records/audit-events/verify" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "valid": true,
  "checked": 48210,
  "anchors_checked": 31
}

Audit data outlives the records

Audit events do not belong to the documents they describe. They reference their subject by type and ID without a database dependency, so deleting a document never deletes its audit history. When a document's content is destroyed through disposition, a tombstone remains: the document row survives with its content hash and audit linkage intact. The complete audit history of a destroyed record therefore remains queryable: every view, every download, the retention policy that governed it, the approval that authorized destruction, and the disposition certificate. The story of a record does not end when its content does.

Querying, filtering, and exporting

Workspace admins can query the audit trail in the UI and through the API, filtered by time range, action, actor, and entity. Common questions the log answers directly: who has accessed this document, ever? What did this API key touch last month? What was destroyed in this period, and who approved each destruction? Which holds were active during the relevant window? The filtered result set can be exported as CSV for auditors, legal teams, or your own scheduled retention of audit extracts, so you can also pull audit data into a SIEM on a schedule.

Query and export audit events

# Everything a specific API key downloaded in June (admin only)
curl "$API_URL/records/audit-events?action=document.downloaded&actor=<api-key-id>&from=2026-06-01&to=2026-07-01" \
  -H "Authorization: Bearer $TOKEN"

# Full history of one document, including after destruction
curl "$API_URL/records/audit-events?entity_type=document&entity_id=$DOCUMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

# Export the same filters as CSV
curl "$API_URL/records/audit-events/export?from=2026-01-01&to=2026-04-01" \
  -H "Authorization: Bearer $TOKEN" -o audit-q1.csv

Audit querying, export, and chain verification are available to workspace admins. Viewers do not have access to the workspace-wide audit log. Audit emission never blocks the operation it records: events are written asynchronously so a logging failure cannot make a document read fail.

Roadmap, not yet available: chain anchors on storage-level WORM (today anchors land in the encrypted, versioned object store with application-level write-once protection, not on S3 Object Lock), permission-change events as first-class audit events, qualified timestamps on audit events, and streaming delivery to external SIEM systems (today, use scheduled CSV export via the API).

Frequently asked questions

How does Talonic detect tampering with the audit log?+

Each event carries a SHA-256 hash of its own contents combined with the hash of the previous event in the workspace, forming a per-workspace hash chain. Editing, deleting, or inserting a past event breaks every hash from that point forward, and the verify endpoint reports the exact first broken event. Events are written in strictly serialized order per workspace, so the chain is linear.

Does deleting a document delete its audit history?+

No. Audit events reference their subject by type and ID without a database dependency on the document row, so no deletion cascades into the log. After disposition, the document's tombstone plus its complete audit history remain queryable: every access, the governing retention policy, the destruction approval, and the certificate.

Are API and integration accesses audited the same way as UI actions?+

Yes. Events are emitted server-side, so a raw API call produces the same audit event as a UI click. API-key actors are recorded with the specific key's identity and label, giving you per-integration accountability if you scope keys per integration.

Can I export audit data for an external auditor or SIEM?+

Yes. The audit-events endpoint supports time, action, actor, and entity filters, and the export endpoint streams the same filtered result set as CSV. Streaming delivery to SIEM systems is on the roadmap; today, scheduled export via the API is the supported pattern.