Audit log

Summary#

Every mutation made through an /api/admin/* endpoint writes one row to the admin audit log: who did it, what they did, what they did it to, and a short detail string. Seventeen distinct actions exist and they are listed in full below. Reads are not recorded, and two mutations sit outside the audited path. The log is exposed on the System Health screen and on the Customers screen, and it can be exported to CSV.

Overview#

The audit log answers "who changed this, and when" for the staff console. It is written by a single helper that every admin mutation calls after its work succeeds. That write is best-effort: if it fails, the action it was recording still stands. The design choice is deliberate. An audit failure must never roll back a customer fix, so the log is a record of intent rather than a transactional guarantee.

The table holds five fields plus an auto-incrementing id.

actor is the email the worker resolved from the caller's token, not a value the browser supplied, so it cannot be spoofed by editing the request body.

The 17 audited actions#

Seventeen places in the worker write an audit row. Every one of them writes it after the change has been applied.

That is seventeen call sites and eighteen possible action strings, because row 1 writes either issue.resolved or issue.unresolved depending on which button was pressed. When you filter by action, customer. matches rows 9 to 14, admin. matches 15 to 17, and config. matches 3 and 4.

What is not audited#

Reading the log#

On System Health#

Admin console → Operations → System Health → Recent admin actions

The CSV header is When (unix),Actor,Action,Target,Meta. The When column is raw unix seconds rather than a formatted date, so a spreadsheet needs a conversion before it reads as a timestamp.

On a customer record#

Admin console → Operations → Customers → Recent actions on this customer

Loading a customer also queries the audit log filtered to that email as the target, most recent 25 rows. It is the fastest way to answer "has anyone touched this account". The empty state is No recorded admin actions on this customer.

Because the filter matches the target column, actions where the customer is the target appear (plan changes, refunds, suspensions, seat removals, social disconnects). Actions where their email only appears in meta, such as a seat removal recorded against a workspace owner, are found by searching the owner instead.

Query limits#

Rows are always returned newest first by id. The console's own page size is 50.

Retention and deletion#

Nothing prunes this table. There is no retention window, no cleanup job, and no endpoint that deletes audit rows. The console cannot clear its own history, which is the property you want from an audit trail. Growth is bounded in practice by the fact that only mutations are recorded, and the console is used by a small number of staff.

If the log ever needs trimming, it has to be done directly against the database by someone with that access. Doing so leaves no record, by definition.

Failure behavior#

That last row is worth remembering during an investigation: an audit entry proves somebody pressed the button, not that anything changed. Confirm the effect on the customer record itself. See Customer lookup and billing.