# Audit Log

> Record who did what, per organization or user, into Cloudflare Analytics Engine: what the kit records, what is stored, and what it is not.

*Canonical: https://makerkit.dev/docs/void-cloudflare/audit/overview*

---

The audit log records who did what: sign-ins, signing out sessions, password, two-factor and passkey changes, renamed organizations, invitations, role changes, removed members, plan changes and what platform admins do. Events go to a [Cloudflare Workers Analytics Engine](https://developers.cloudflare.com/analytics/analytics-engine/) dataset. No Postgres table, no extra vendor.

## What the Kit Records

| Action | When | Metadata |
|---|---|---|
| `kit.organization.created` | A user creates an organization | none |
| `kit.organization.renamed` | An organization is renamed | none |
| `kit.organization.deleted` | An organization is deleted: one event, none for its members | none |
| `kit.member.invited` | An invitation is sent (or an expired one is sent again). The organization is the scope; the address and the invitation id are never stored | `role` |
| `kit.invitation.revoked` | A pending invitation is canceled | `role` |
| `kit.member.joined` | An invitation is accepted; the actor is the new member (the admin while impersonating, with the member as the impersonated user) | `role` |
| `kit.member.left` | A member leaves; the actor is the member (as above while impersonating) | none |
| `kit.member.removed` | A member is removed; the target is the member's user id | none |
| `kit.member.role_changed` | A member's role changes; the target is the member's user id. `fromRole` is read just before the change: two role changes at the same moment can both name the old role | `fromRole`, `toRole` |
| `kit.admin.user_banned`, `kit.admin.user_unbanned` | A platform admin bans or unbans a user. The admin is the actor; the user is the scope and the target | none |
| `kit.admin.role_changed` | A platform admin sets a user's platform role | `role` |
| `kit.admin.sessions_revoked` | A platform admin signs out one session or all of a user's | `which`: `one` or `all` |
| `kit.admin.impersonation_started`, `kit.admin.impersonation_stopped` | A platform admin starts or stops being signed in as a user. The target is the user; a stop names the admin as actor and the user as the impersonated user | none |
| `kit.admin.outbox_job_replayed`, `kit.admin.outbox_job_cancelled` | A platform admin replays or cancels a background job. The scope is the job's organization, else the admin; the target is the job | `jobId`, `kind` |
| `kit.billing.subscription_started` | A subscription is created (from Stripe's webhook; the actor is `stripe-webhook`; the scope is the organization or user billed) | `plan`, `stripeEventId`, `occurredAt` |
| `kit.billing.plan_changed` | A subscription moves to another plan | `fromPlan`, `toPlan`, `stripeEventId`, `occurredAt` |
| `kit.billing.cancelled` | A subscription is set to end at the period's end, or has ended | `at`: `period_end` or `ended`, `plan`, `stripeEventId`, `occurredAt` |
| `kit.billing.resumed` | A subscription set to end is kept | `plan`, `stripeEventId`, `occurredAt` |
| `kit.auth.signed_in` | A sign-in succeeds, by any method; a second factor counts once, at its code | `method`: `password`, `email_code`, `magic_link`, `passkey`, `two_factor`, `email_verification`, `social` |
| `kit.auth.sessions_revoked` | A user signs out all their sessions, or all the others | `which`: `all` or `others` |
| `kit.auth.password_changed` | A password is changed, or reset from the emailed link | `via`: `change` or `reset` |
| `kit.auth.two_factor_enabled`, `kit.auth.two_factor_disabled` | A user turns two-factor on (when the code confirms it) or off | none |
| `kit.auth.passkey_added`, `kit.auth.passkey_removed` | A passkey is saved or deleted | none |
| `kit.auth.backup_codes_regenerated` | A user generates new two-factor backup codes (the old ones stop working) | none |

Billing events carry plan names, Stripe's event id and when Stripe sent it (`occurredAt`, epoch seconds: read events in that order, as two webhooks can be handled out of order), never prices, URLs or payloads; a webhook Stripe delivers twice records once, and in the rare crash between the write and its acknowledgement the same event id can appear twice. Each event is scoped to the user or the organization it happened to.

Not recorded: an email change, linking or unlinking a social account, signing out a single session, an invitation resent before it expires or declined, a password set by server code or by a platform admin, and a platform admin turning off a user's two-factor. Two requests sent at the same moment (signing out all sessions, turning two-factor on or off) can record twice.

## What Is Stored

One data point per event: the action (`kit.organization.renamed`), the scope (`organization:<id>`), the actor (the user, or the admin while impersonating, plus the impersonated user; or a system name such as `stripe-webhook`), an optional target, a severity and a small flat metadata object. Cloudflare sets the time.

**Ids only.** No emails, IP addresses, user agents, names or free text. Analytics Engine rows can't be deleted, so nothing that identifies a person goes in. Ids are pseudonymous; your privacy policy should say that audit events (ids and actions) are kept for 90 days and can't be erased early.

## What It Is Not

- **Best effort, not a compliance record.** An event is written after the action commits. If the Worker dies between the two, the event is lost. Above about 1 million writes a minute Analytics Engine samples; kit actions are low-volume (no per-request events).
- **90 days.** Analytics Engine keeps data for 90 days.
- **Platform admins only.** Events are read on the admin user and organization pages ([Read the audit log in the admin](./reading-the-log)); no organization member or user can read them.
- **Failed sign-ins are not recorded.** Only successful ones are, so attempts can't flood the dataset; failures stay in the rate-limit logs.

## Turn It On

The binding is declared for you: `apps/web/void.config.ts` binds the dataset named in `apps/web/config/audit-dataset.config.ts` (`AUDIT_EVENTS` → `audit_events`) through `analytics_engine_datasets`. On the first deploy Cloudflare may ask you to enable Analytics Engine for the account (error 10089): open **Analytics Engine** in the Cloudflare dashboard and select **Enable**.

Without the binding (local development, tests) each event is written as one `audit` line in the logs instead. Change the dataset name only before the first deploy: events stay in the dataset they were written to.

## What Happens When Recording Fails

In production a failed record never changes the response: it logs `audit_write_failed` with the action and ids, never the metadata, and the action goes on. In development and tests the same failure throws, so a wrong action or metadata shows up at once.

## Next

- [Add your own actions and scope types](./adding-actions)
- [Read the audit log in the admin](./reading-the-log)
