Skip to main content

Audit trail

This recipe shows how to retrieve the immutable audit trail for your tenant. The audit trail captures every state change with actor, timestamp, before/after state, and rationale, and is preserved per regulatory retention requirements.

Endpoint​

GET /v1/audit-trail

Returns an array of audit trail entries sorted by timestamp descending.

Prerequisites​

  • A valid tenantId and bearer JWT.
  • The user must have at least one of: tenant_admin, tenant_compliance, tenant_auditor.

Request​

curl -X GET "https://api.falconveritas.com/v1/audit-trail?fromDate=2026-08-01&toDate=2026-08-22&actor=user:alice&action=exception.resolve" \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json"

Response​

{
  "items": [
    {
      "id": "audit-001",
      "tenant_id": "f1a4e6e2-4b3e-4d2e-9b9c-3a2e9b1f4d5a",
      "actor": "user:alice",
      "action": "exception.resolve",
      "resource_type": "exception",
      "resource_id": "exc-001",
      "before_state": {
        "status": "in_review",
        "assigned_to": "user:alice"
      },
      "after_state": {
        "status": "resolved",
        "resolution_action": "manual_match"
      },
      "rationale": "Bank fee was recorded as separate line item; manually matched to GL entry.",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "timestamp": "2026-08-22T15:30:00Z",
      "signed_hash": "sha256:abc123..."
    }
  ],
  "next_cursor": null
}

Filter parameters​

ParameterTypeDescription
limitinteger (1-500, default 100)Maximum entries to return
cursorstringPagination cursor
fromDateISO 8601 datetimeEntries on or after this timestamp
toDateISO 8601 datetimeEntries on or before this timestamp
actorstringFilter by actor (user:<id>, system:<job>, cron:<name>)
actionstringFilter by action type
resource_typestringFilter by resource type (exception, rule, account, etc.)
resource_idstringFilter by specific resource

Immutability and retention​

Audit trail entries are immutable once written. FVI's security_events table enforces this through a row-level trigger that rejects any UPDATE or DELETE on existing rows. Entries are retained for the maximum of any applicable regulatory requirement (SOC 2: 1 year online + 6 years archive; ISO 27001: 3 years; PCI DSS: 1 year online + immediate archival).

The signed_hash field is computed over the entry's content using the tenant's signing key, providing a tamper-evident seal. Any modification to the entry's content would invalidate the hash.

Use cases​

  • Compliance evidence — generate audit trail extracts for SOC 2, ISO 27001, or PCI DSS evidence packs.
  • Forensic investigation — reconstruct the sequence of events during a security incident.
  • Access review — show all actions taken by a specific user during a review period.

Code samples​

TypeScript​

import { FVI } from '@falconveritas/sdk';

const fvi = new FVI({
  baseUrl: 'https://api.falconveritas.com',
  bearer: process.env.FVI_JWT!,
  tenantId: process.env.FVI_TENANT_ID!,
});

const trail = await fvi.auditTrail.list({
  fromDate: '2026-08-01',
  toDate: '2026-08-22',
  actor: 'user:alice',
  limit: 500,
});

for (const entry of trail.items) {
  console.log(`${entry.timestamp} — ${entry.actor} — ${entry.action} — ${entry.resource_id}`);
}

Python​

from falconveritas import FVI

client = FVI(
  bearer=os.environ["FVI_JWT"],
  tenant_id=os.environ["FVI_TENANT_ID"],
)

trail = client.audit_trail.list(
  from_date="2026-08-01",
  to_date="2026-08-22",
  actor="user:alice",
  limit=500,
)
for entry in trail.items:
  print(f"{entry.timestamp} — {entry.actor} — {entry.action} — {entry.resource_id}")

Last updated: 2026-08-22 · Page owner: Documentation · Source: src/lib/api/audit-trail.ts.