Most teams believe they already have audit logging, because they have logs. They are not the same thing, and the difference becomes obvious the first time someone outside your company asks a question of them.
Application logs are written for the person debugging. They are unstructured, they are sampled, they rotate after a fortnight, and they contain whatever the engineer thought was interesting that day. None of those properties are acceptable in an audit trail.
The shape
An audit event answers a fixed set of questions: who did it, what did they do, to what, when, and from where. Actor, action, target, timestamp, context. If any of those is missing the event is close to useless, because the question being asked is always some join across them.
Actions should be named as a stable vocabulary — invoice.exported, member.role_changed — not free text. The reviewer's first move is to filter, and they cannot filter on prose.
- Actor: who, including whether it was a person, an API key or the system
- Action: a stable, documented name
- Target: the object, with an identifier that still resolves later
- Context: address, user agent, request id
Append-only means append-only
An audit log you can edit is not evidence. That means no updates, no deletes, and no retroactive corrections — if something was recorded wrongly, the correction is a new event that references the old one.
It also means the retention conversation is real. Enterprise customers routinely ask for a year, sometimes seven. Design for that from the start; retrofitting retention onto a table that was never meant to grow is an unpleasant migration.
An audit log you can edit is not evidence. Corrections are new events, not overwrites.
Give it to the customer
The final step is the one that turns a compliance checkbox into something people value: let the customer see their own events, and export or stream them into whatever tooling they already run.
A security team that can answer its own questions without opening a ticket with you is a security team that stops being a blocker in your sales cycle.
Everything here, already built
Sign-in, enterprise SSO, directory provisioning, roles and an audit trail behind one API. Start with the quickstart and have a working sign-in this afternoon.