Auth Events and Auditing

Auth Events & Auditing

Seamless Auth tracks authentication activity through explicit auth event records.

These events are one of the main reasons the system is inspectable by operators instead of behaving like a black box.

Mental Model

User or system action
  -> auth event recorded
  -> sensitive metadata redacted
  -> stored
  -> queried by admin and metrics routes

What An Auth Event Is

An auth event is a record of something that happened in the auth system.

Common examples include:

user_created
registration_success
verify_otp_success
webauthn_registration_success
login_failed
oauth_login_success
totp_verify_success
admin_session_revoked
admin_device_replacement_recovery
request_suspicious
bootstrap_admin_granted

Exact event types are implementation details, but the event stream should cover authentication, MFA, OAuth, admin actions, suspicious requests, and recovery flows.

Important Event Fields

Field	Description
`id`	Event ID
`user_id`	Associated user when available
`type`	Event type
`ip_address`	Origin IP
`user_agent`	Device info
`metadata`	Additional redacted structured context

Redaction Rule

Auth event metadata must not expose raw secrets or browser-local key material.

Sensitive values include:

tokens and refresh tokens
OTP values
magic-link URLs and tokens
OAuth state, codes, provider tokens, and provider client secrets
PRF salts and PRF output
TOTP secrets
private keys
raw recovery material

The API redacts sensitive metadata before storing events. Docs should follow the same rule and avoid example payloads that normalize leaking secrets.

Why Events Matter

Auth events are useful for:

debugging auth flows
building operator dashboards
detecting suspicious activity
auditing admin-sensitive flows
understanding where auth friction is happening
supporting login policy and lockout investigations

Security Use Cases

You can use auth events to:

detect repeated login failures
track unusual IP behavior
surface suspicious request patterns
review bootstrap and admin-related activity
investigate OAuth account-linking failures
confirm session revocation and device replacement recovery actions

How The Dashboard Uses Them

The admin dashboard uses auth event data to power:

event browsing
grouped event summaries
timeseries metrics
login success/failure stats
anomaly investigation flows
user detail audit context

That makes the event stream useful for both debugging and operations.