Audit Event Catalog
The closed set of audit actions shipped by the starter. The source of truth is convex/audit/validators.ts (auditActionValidator and AUDIT_ACTION_CATEGORY). This is a minimal starter audit, not a compliance guarantee.
The closed set of audit actions shipped by the starter. The source of truth is
convex/audit/validators.ts
(auditActionValidator and AUDIT_ACTION_CATEGORY). This is a minimal
starter audit, not a compliance guarantee.
Each event carries: action, derived category, result
(success | failure | denied), an actor snapshot, an optional
organizationId, an optional target, a summary, optional metadata, and
createdAt.
Events
| Action | Category | Emitted from | Notes |
|---|---|---|---|
auth.user.created | auth | Better Auth user.onCreate trigger | One event per new account. |
auth.user.deleted | auth | Better Auth user.onDelete trigger | Covers account deletion too — Better Auth deleteUser runs the same trigger, so there is no separate event. |
organization.created | organization | organizations.createWorkspace | Team-mode workspace creation. |
organization.updated | organization | organizations.updateOrganization | Rename. |
organization.deleted | organization | organizations.deleteOrganization | Profile status → deleted; includes revoked grant count. |
organization.suspended | organization | admin.organizations.suspend | Super-admin write; result reflects success/failure. |
organization.reactivated | organization | admin.organizations.reactivate | Super-admin write. |
member.invited | member | members.inviteMember | Metadata: invitee email, role. |
member.role_changed | member | members.updateMemberRole | Metadata: member id, new role. |
member.removed | member | members.removeMember | Metadata: member id, role if known. |
billing.grant_created | billing | billing.grants sync | System actor (webhook/manual). Metadata: provider, plan key, count. |
billing.grant_revoked | billing | billing.grants sync | System actor. Metadata: provider, plan key, count. |
billing.subscription_updated | billing | provider upsert*Subscription | Fires on status change/creation. Metadata: provider, plan key, status, previous status. |
security.stepup_challenge_created | security | security.createSensitiveVerificationChallenge | A verification code was requested. Never the code. |
security.stepup_challenge_consumed | security | security.consumeSensitiveVerificationChallenge | Step-up succeeded. |
security.stepup_challenge_failed | security | security.consumeSensitiveVerificationChallenge | Metadata: reason (invalid/expired/too_many_attempts/consumed). |
admin.access_denied | admin | admin write mutations (resolveSuperAdminAccess) | An authenticated non-admin attempted an admin write. Committed via a structured-result return (not a throw). Anonymous callers are not recorded. |
Result semantics
success— the action completed.failure— the action was attempted but failed after authorization (e.g. suspending an already-suspended workspace).denied— an authorization check rejected the caller (admin.access_denied).
Adding a new event
Add a literal to auditActionValidator, the AuditAction union, and
AUDIT_ACTION_CATEGORY, then call writeAuditEvent. See
Recipe: Write an Audit Event.