Chain Integrity

Stateway's audit log is tamper-evident. Each entry includes a cryptographic hash (entryHash) computed over the entry's own content plus the hash of the immediately preceding entry (prevEntryHash). This creates an unbroken chain: deleting, inserting, or modifying any entry in the middle produces a detectable mismatch.

How it works

When an audit log entry is written:

1. Stateway fetches the entryHash of the most recent entry for the tenant.
2. It computes a new hash over the combined content of the new entry and the previous hash.
3. Both prevEntryHash and entryHash are stored alongside the entry.

The first entry of a tenant has no predecessor; its entryHash is computed using the sentinel value "GENESIS" in place of prevEntryHash.

No application code path ever deletes or updates audit log entries.

Verifying the chain

GET /v1/audit/verify re-computes and validates the hash chain over a time range:

curl "https://api.stateway.io/v1/audit/verify?from=2026-05-01T00:00:00Z&to=2026-05-31T23:59:59Z" \
  -H "X-API-Key: sw_live_your_key"

Valid chain

{
  "data": {
    "status": "valid",
    "entries_verified": 1420,
    "first_entry_id": "log_01j...",
    "last_entry_id": "log_99j...",
    "from": "2026-05-01T00:00:00Z",
    "to": "2026-05-31T23:59:59Z"
  }
}

Tampered chain

{
  "data": {
    "status": "tampered",
    "entries_verified": 89,
    "first_broken_entry_id": "log_45j...",
    "break_detected_at": "2026-05-15T14:32:10Z",
    "detail": "entry_hash mismatch: expected a3f1... got 9b2c..."
  }
}

status: "tampered" means verification stopped at the entry identified by first_broken_entry_id. All entries before that point validated correctly.

What to do if tampering is detected

A status: "tampered" result indicates that one or more audit log entries were modified, deleted, or inserted outside the normal application path. Preserve the response body as evidence and contact Stateway support.

Parameters

Parameter	Type	Required	Description
from	ISO 8601	Yes	Start of the time range to verify
to	ISO 8601	Yes	End of the time range to verify

Performance

Verification reads entries sequentially and re-computes each hash in memory. The endpoint processes up to 10,000 entries per call and enforces a 30-second timeout.

For large time ranges, verify in smaller windows:

# Verify one week at a time
curl "https://api.stateway.io/v1/audit/verify?from=2026-05-01T00:00:00Z&to=2026-05-07T23:59:59Z" \
  -H "X-API-Key: sw_live_your_key"

Chain verification is designed for periodic compliance audits and spot checks — not continuous polling.