👁

Audit Logging

Immutable, SOC 2 compliant event logging — who did what, when, and from where.

Last reviewed 2026-04 · Engineering · Owned by AI Safety Officer

Overview

Every significant action in Votriz is recorded in an immutable audit log. The log cannot be modified or deleted — a database trigger physically prevents UPDATE and DELETE operations even from a database superuser. This satisfies SOC 2 Trust Service Criteria CC7.1 (system monitoring) and CC7.2 (anomaly detection).

Immutability guarantee

The security_audit_log table is protected by a trigger that raises on any modification attempt:

CREATE TRIGGER no_audit_update
  BEFORE UPDATE OR DELETE ON security_audit_log
  FOR EACH ROW
  EXECUTE FUNCTION prevent_audit_modification();

-- ERROR: security_audit_log is immutable — UPDATE and DELETE are prohibited

This means:

Application code cannot modify past audit entries
A compromised database admin cannot silently alter the log
Audit entries are evidence-grade records suitable for legal hold

What is logged

Category	Actions
Authentication	login, login_failed, password_change, password_reset, mfa_setup_initiated, mfa_enabled, mfa_login_succeeded, mfa_login_failed, mfa_disabled, mfa_recover_started, mfa_recovered
Content	create, approve, reject, edit, publish, delete
Email	campaign_create, campaign_send, subscriber_delete, lead_generate
Channels	connect, disconnect, token_refresh
Members	invite, remove, role_change, permission_grant
Billing	plan_change, checkout_initiated, portal_opened, payment_failed, cancel
Settings	update, white_label_change, export_data
AI	quality_report
Security	isolation_proof_viewed, drill_completed

Entry structure

Field	Description
`log_id`	Sequential bigint — proves ordering, no gaps
`org_id`	Which organization
`user_id`	Who performed the action (NULL for system actions)
`user_email`	Denormalized — survives user deletion
`user_role`	Role at time of action
`ip_address`	Client IP
`user_agent`	Browser / API client
`action`	What happened (e.g. `content.approve`)
`resource_type`	What was affected (`content`, `brand`, …)
`resource_id`	Specific resource UUID
`details`	Action-specific JSONB context
`request_id`	Correlation id matching the response's `X-Request-Id` header and the access log
`created_at`	UTC timestamp

Querying

Owner and admin roles can query the log via the API or in the dashboard under System → Audit Log.

GET /audit/log?action=auth.login&start_date=2026-04-01&limit=50
Authorization: Bearer <owner-token>

Available filters: action, user_id, resource_type, resource_id, ip_address, start_date, end_date. Pagination via limit + offset (limit capped at 500 per page).

Aggregate dashboard data

GET /audit/log/summary?days=30
Authorization: Bearer <owner-token>

Returns total events, unique IPs, failed-auth count, by-category counts, and the top 10 active users.

Exporting

Owners can export the full audit log as CSV or JSON for compliance review or long-term archival:

GET /audit/log/export?format=csv&start_date=2026-01-01
Authorization: Bearer <owner-token>

# Filename: votriz_audit_log_YYYYMMDDTHHMMSSZ.csv

Export is owner-only (admins can read but not export). Date range is optional; without it you get everything since account creation.

Retention

Audit log entries are retained for 7 years — the SOC 2 evidence window. Entries are never automatically purged. The immutability trigger ensures historical entries remain unchanged regardless of account status, deletion requests, or backup rotation. This is intentional: data deletion under GDPR Art 17 covers personal data the customer produced, not the audit trail of what happened to that data.