SaaS Audit Log Architecture: Immutable Events, Multi-Tenant Isolation, Retention, and SIEM Streaming

SaaS Audit Log Architecture: Immutable Events, Multi-Tenant Isolation, Retention, and SIEM Streaming

A serious B2B SaaS customer eventually asks a question ordinary application logs cannot answer cleanly:

> Who changed this setting, what changed, when did it happen, and can we trust the historical record?

That is an audit-log problem.

Audit logs are not debug logs with longer retention. They are a customer- and security-facing record of meaningful actions: authentication changes, permission updates, API-key creation, sensitive exports, configuration changes, support actions, and increasingly AI-agent operations.

For enterprise SaaS, the audit trail becomes part of the product. Customers may expect to search it, export it, query it through an API, or stream it into their SIEM.

Audit Logs Are Not Application Logs

Diagnostic logs answer engineering questions:

request failed
database timeout
job retried
dependency latency

Audit logs answer security and business questions:

user changed member role
API key was created
admin changed retention policy
customer exported data
AI agent changed a resource

Diagnostic logs can be sampled or deleted quickly. Audit records may need stronger integrity, access controls, and retention. Do not build customer audit history by querying whatever application logs happen to remain.

What Should Be Audited?

Do not record every click or SQL query. Record actions meaningful for security, administration, compliance, or investigation.

Useful categories include:

user.invited
user.removed
role.changed
permission.granted
mfa.enabled
session.revoked

api_key.created
api_key.rotated
api_key.revoked
integration.connected

customer_data.exported
personal_data.deleted
bulk_export.started

organization.settings_changed
retention_policy.changed
subscription.changed
refund.approved

agent.tool_invoked
agent.approval_granted
agent.resource_changed
agent.data_exported

The event catalog should describe domain actions, not implementation chatter.

Use a Stable Event Contract

A practical event can contain:

event_id
schema_version
event_name
occurred_at
recorded_at

tenant_id

actor_type
actor_id

target_type
target_id

outcome

request_id
trace_id
session_id

source_ip
user_agent

changes
metadata

Not every event needs every field, but shared fields need stable semantics.

Use globally unique event IDs for pagination, exports, deduplication, replay, and SIEM delivery.

Prefer stable event names such as organization.member_role_changed instead of making an English sentence the integration contract.

Actor, Action, Target, Outcome

Every useful event should answer:

Who or what acted?
What happened?
Which resource was affected?
Which tenant owned it?
What was the outcome?
When?

Modern SaaS must support more than human actors.

A human can be actor_type=user. An API key can be actor_type=api_key. A background worker can be actor_type=service.

Support operators should be recorded as the actual operator rather than pretending the customer performed the action.

AI agents should be identifiable separately from the human who delegated authority:

actor_type = ai_agent
actor_id = support_agent_prod
delegated_by = usr_18
run_id = run_991

This becomes essential as agents perform real mutations.

Tenant Context Must Be Trusted

tenant_id should come from authenticated server-side context:

authenticated principal
      ↓
trusted membership or API-key ownership
      ↓
resolved tenant
      ↓
domain operation
      ↓
audit event

Do not let request JSON choose the authoritative audit tenant.

A wrongly attributed event can become a cross-tenant information leak.

Isolation Must Apply Everywhere

Tenant isolation must protect:

• dashboard listing;
• search;
• event detail;
• CSV export;
• API access;
• SIEM streaming;
• support tooling.

Every customer query must be scoped to the authenticated tenant before optional filters are applied. Opaque event IDs are not authorization.

Audit Logs Are a Product Surface

Enterprise audit logging is not finished when the table exists.

A useful customer interface should support time range, actor, action, target, outcome, pagination, event detail, safe search, and export.

Larger customers may expect an API or streaming destination for security tooling.

WorkOS Audit Logs demonstrates this product pattern: organization-scoped events can be retained, exported, and streamed into external systems. The broader lesson is that audit history is both security infrastructure and SaaS functionality.

Generate Events at Trusted Domain Boundaries

Do not generate authoritative records from frontend button clicks. A click can be forged or followed by a failed operation.

Generic HTTP middleware can also be too shallow. It may know that POST /members/77 returned 200 but not that a role changed from viewer to admin.

Generate the event where the business operation is understood:

changeMemberRole
  ↓
authorize
  ↓
load old state
  ↓
perform mutation
  ↓
record member_role_changed

At that boundary the server knows the trusted actor, tenant, target, old value, new value, and outcome.

What If the Audit Write Fails?

If a sensitive mutation succeeds but its required audit event disappears, history is incomplete.

When domain and audit data share a transactional database, use the same transaction:

BEGIN
UPDATE domain state
INSERT audit_event
COMMIT

Either both persist or neither does.

If processing is asynchronous, use a transactional outbox:

BEGIN
UPDATE domain state
INSERT durable outbox event
COMMIT

A worker later delivers the event to the audit store and downstream systems.

This avoids the classic dual-write failure where the database commits but message publication fails.

Never Put the Customer SIEM on the Critical Path

A customer destination can be slow, unavailable, rate-limited, or misconfigured.

Prefer:

business mutation
      ↓
durable internal audit record
      ↓
asynchronous delivery
      ↓
customer SIEM

The SIEM is a sink, not your transaction coordinator.

Append-Only by Default

Normal application roles should not update or delete historical audit records.

If a record needs correction, append a correction or superseding event where policy allows it.

Use separate database privileges so the normal application role cannot casually rewrite history. Retention deletion can run through a dedicated controlled path.

Be Precise With "Immutable"

An append-only table is useful, but it is not automatically cryptographically immutable.

Possible assurance levels include:

1. Application-level append-only behavior.
2. Database roles that prohibit normal UPDATE/DELETE.
3. Immutable archive storage.
4. Tamper-evident hashes or signatures.

Hash chains can make historical alteration detectable, but add complexity around serialization, concurrency, partitioning, key management, verification, retention, and recovery.

Use cryptographic tamper evidence when the threat model or contract justifies it. Do not add it merely for marketing.

Separate Authoritative Storage From Search

At larger scale, Elasticsearch/OpenSearch or ClickHouse may be useful for audit search.

That system should not necessarily be the only source of truth.

Domain operation
      ↓
Authoritative audit store
      ↓
event pipeline
      ↓
Search / analytics projection

If the search index is rebuilt, authoritative history remains.

PostgreSQL Is Often Enough

You do not need Kafka, Elasticsearch, and ClickHouse on day one.

For many SaaS products:

PostgreSQL audit_events
+ appropriate indexes
+ optional time partitioning
+ background export workers

can handle substantial workloads.

Common access patterns need indexes beginning with tenant_id and occurred_at, plus targeted actor, event-name, and target indexes.

Add dedicated search infrastructure when real workload justifies it.

Before/After Values Are Useful and Dangerous

A role-change event is more useful when it contains:

role:
  from = viewer
  to = admin

But blindly serializing database rows can leak password hashes, API secrets, tokens, payment data, personal information, or large documents.

Use an allowlist of auditable fields.

Audit that a secret was created, rotated, or revoked. Never record the secret itself.

Data Minimization Still Applies

Audit logs are not exempt from privacy requirements.

IP addresses and user agents can help investigations but may also be personal data.

Define whether they are collected, retention duration, who can view them, export behavior, and masking where appropriate.

Version the Event Schema

Audit events become long-lived contracts, especially when customers build SIEM detections against them.

Do not silently change field meaning.

Prefer additive changes. For breaking semantic changes, introduce a new schema version or event version and migrate consumers deliberately.

SIEM Streaming Is a Delivery System

Enterprise customers may want events in Splunk, Datadog, Elastic, Sentinel, object storage, or webhook destinations.

Track destination, checkpoint, attempts, last error, next retry, and status.

Support retries with backoff, bounded queues, replay, backpressure, pause/resume, tenant isolation, and destination health.

The authoritative event should remain stored after delivery succeeds.

At-Least-Once Delivery Is Practical

Exactly-once delivery across arbitrary customer systems is difficult.

A pragmatic contract is:

at-least-once delivery
+ stable event_id
+ downstream deduplication

If a timeout occurs after the destination accepted an event, retry may create a duplicate. Stable IDs let consumers deduplicate safely.

Replay Is an Enterprise Feature

Customers will eventually ask to resend events after a broken SIEM destination.

Design for replay by time range or checkpoint.

Replay should preserve original event IDs and timestamps. Protect it with authorization and rate limits, and audit who initiated it.

Retention Is Product Policy

The architecture should make retention explicit rather than inheriting an observability vendor's TTL.

Retention policy must consider:

• authoritative database;
• search projections;
• exports;
• backups;
• delivery buffers;
• archives.

Longer is not automatically better. Retain what contracts, compliance, security, and privacy policy actually require.

Audit the Audit System

Sensitive audit history can reveal identities, security changes, IP addresses, exports, and admin activity.

Important administrative events can include:

audit_log.exported
audit_retention.changed
audit_stream.created
audit_stream.destination_changed
audit_replay.started

Access to audit history should itself be authorized and, where appropriate, audited.

Support and Impersonation

If an internal operator enters a customer account, record the operator identity, tenant, impersonated identity if relevant, reason or ticket where appropriate, and sensitive actions performed.

Do not write those events as though the customer performed them.

AI Agents Need Better Audit Semantics

An AI agent can perform multiple actions under delegated authority.

Useful context can include:

tenant
delegating human
agent identity
agent run
tool call
approval
target resource
outcome

Do not store model chain-of-thought as an audit trail.

Audit externally meaningful actions, approvals, and state changes.

Correlate Audit With Observability

Audit and diagnostic systems should remain separate, but correlation is valuable.

A trace or request ID can let an authorized engineer move from:

customer-facing audit event
→ distributed trace
→ internal service logs

without exposing internal diagnostic details to customers.

Common Anti-Patterns

Avoid:

• building audit history from sampled application logs;
• recording authoritative events from the frontend;
• storing whole request bodies;
• recording only human actors;
• synchronous delivery to customer SIEM;
• calling a mutable table cryptographically immutable;
• global queries without tenant scoping;
• changing schemas without versioning;
• deleting authoritative events after export;
• unlimited retention by default.

A Practical Early Architecture

A strong initial implementation can be:

Application / API
      ↓
Domain transaction
      ↓
PostgreSQL
  - audit_events
  - audit_outbox
  - audit_destinations
  - delivery_checkpoints
      ↓
Background worker
  ├── search projection
  ├── export generation
  └── SIEM delivery

Add partitioning when volume justifies it. Add ClickHouse or a search engine when query workload justifies it. Add immutable archives or cryptographic tamper evidence when contracts or threat models justify them.

Correct semantics and durability matter more than infrastructure count.

Core Invariants

1. Every customer-visible event belongs to exactly one authoritative tenant.
2. A critical mutation and its required audit evidence cannot silently diverge.
3. Normal application roles cannot rewrite historical events.
4. Secrets never enter audit payloads.
5. Reads, exports, APIs, and streams enforce tenant isolation.
6. Stable event IDs survive retries and replay.
7. External SIEM failures cannot block normal product availability.
8. Schema changes do not silently reinterpret historical records.
9. Retention applies consistently across authoritative and derived stores.
10. Support and AI-agent actions preserve the real acting principal and delegation context.

Production Checklist

• Stable event names and schema versions exist.
• Actor, target, tenant, outcome, and time have defined semantics.
• Machine, support, and AI-agent actors are representable.
• Tenant context comes from trusted server state.
• Customer queries are tenant-isolated.
• Critical mutations cannot silently lose required audit evidence.
• Historical records are append-only for normal application roles.
• Secrets are excluded at the source.
• Before/after fields use allowlists.
• Retention policy is explicit.
• Search is not the only authoritative copy.
• SIEM delivery is asynchronous and retryable.
• Replay preserves original event identity.
• Audit exports and stream configuration are authorized.
• Support and impersonation activity is visible.
• AI-agent actions preserve delegation and approval context.

Final Takeaway

A production SaaS audit system is not:

application logs + longer retention

It is:

trusted domain action
      ↓
structured tenant-scoped event
      ↓
durable append-only evidence
      ↓
customer search / export / API
      ↓
reliable SIEM delivery

The strongest systems keep the authoritative record durable, the schema stable, tenant isolation unavoidable, secrets out of the payload, and external destinations asynchronous.

As SaaS products move upmarket—and as AI agents perform more real work—the question "who or what changed this?" becomes a product requirement, not merely an observability concern.

That is why audit-log architecture belongs in the core SaaS design.

Sources and Further Reading

• WorkOS Audit Logs: https://workos.com/docs/audit-logs
• WorkOS Audit Logs Events: https://workos.com/docs/audit-logs/events
• WorkOS Log Streams: https://workos.com/docs/audit-logs/log-streams
• Linear Security and Access documentation: https://linear.app/docs/security-and-access
• OWASP Logging Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
• OpenTelemetry Logs Data Model: https://opentelemetry.io/docs/specs/otel/logs/data-model/
• NIST SP 800-92, Guide to Computer Security Log Management: https://csrc.nist.gov/pubs/sp/800/92/final