Audit log (auth events)
A security history of logins, failed attempts, role changes, token grants, and other events that answer who did what and when.
What it is
An auth audit log is the durable timeline of security-sensitive identity events: successful and failed logins, password and MFA changes, session revocation, role grants, token creation, and staff impersonation. Each event says when it happened, what happened, who acted, which account or resource was affected, and enough request context to investigate it.
Reach for it before enterprise customers ask for a security history or support needs to explain an account takeover. Keep the event names stable and structured so a customer can filter 'role.changed' without parsing prose. GitHub's organization audit log is the shape customers picture, with stable event names such as org.add_member beside actor, time, and country. Actor and subject must be separate, especially when an admin changes another user.
The log itself is sensitive. IP addresses and user agents can be personal data, while passwords, session cookies, reset links, and raw tokens must never appear at all. Make records append-only while retained, restrict who can read them, set a stated retention window, and do not count a client-side analytics event as security evidence.
Ask AI for it
Add an append-only auth_events table in PostgreSQL with event_id, event_type, actor_id, subject_id, organization_id, session_id, request_id, outcome, ip_address, user_agent, metadata jsonb, and an RFC 3339 created_at timestamp. Define stable event names for login success and failure, logout, MFA changes, password reset, session revocation, role changes, token grants, and impersonation. Insert server-side in the same transaction as each state change, grant the application role no UPDATE or DELETE permission, and redact keys matching password, secret, cookie, authorization, and token before serialization. Index subject_id plus created_at and organization_id plus created_at, expose a least-privilege admin viewer, and delete records only through a documented retention job.