Audit logs

Support operations

Customer and platform views

Organization audit access requires the audit.read entitlement. GET /saas/audit returns the newest events first, and pages by the last event seen: pass the Id of the last event as AfterId to get the events after it. The audit log only grows, so this stays fast however far back a customer pages, and events recorded in the meantime do not shift later pages. Platform search supports organization, category, action, outcome, date range, and free text, with authorization enforced by the service.

Organization members use /audit. Platform Admin users search and export the cross-organization audit stream from /admin/security.

Event shape

The audit log is two tables, because a table's rows either all belong to an organization or none do:

// On a connection confined to an organization, the event gets it
Db.Insert(new SaasAuditEvent { Category = "workspace", Action = "profile.updated", UserId = userId });

Db.Insert(new PlatformAuditEvent { Category = "plan", Action = "version.published", UserId = userId });

An organization's log is an ordinary tenant-owned table, so it is isolated, exported, and retained like every other, and the customer's audit page cannot show another organization's events. SaasAudit rejects an event written to the wrong log. Operators see both in one list, which queries the two tables and merges them.

Both contain category, action, outcome, user, subject, request correlation, network/client context, timestamp, and sanitized metadata. Use registered, stable action names so filters, exports, alerts, and downstream integrations do not depend on prose.

Recording events

Record an event at the point a meaningful decision commits: successful and denied privileged changes, billing transitions, credential management, lifecycle requests, support access, and operator actions. Include enough identifiers to investigate the event without copying entire request bodies.

The audit helper redacts known sensitive keys and credential-like patterns and limits metadata size. Redaction is a backstop, not permission to pass secrets. Never audit passwords, raw API keys, Stripe secrets, invitation tokens, export contents, or uploaded file bytes.

Retention and export

Saas.AuditRetentionDays is the global default; organization retention policy and legal hold can change cleanup behavior. CSV exports apply the same tenant and role filters as the list APIs.

Audit history supports product investigation but is not automatically a regulated write-once ledger. Products with formal immutability requirements should stream events to appropriately controlled external storage.

Adding an audited operation

1. choose an existing category or register a deliberate new one;
2. use a stable past-tense action;
3. record organization, user, subject, outcome, and request ID;
4. add only allow-listed, sanitized metadata;
5. test success, denial, and cross-tenant behavior;
6. include the new event in relevant retention/export reviews.

Verify

Exercise each privileged flow, inspect customer and platform views, export filtered CSV, test redaction with credential-shaped values, verify pagination and tenant isolation, and run retention with and without legal hold.

Related documentation

• API keys
• Data lifecycle
• Support operations