Audit Log Events

Every security-relevant action generates an audit log entry. Events are namespaced by resource type.

Event naming convention

Events follow the pattern resource.action:

user.login — a user signed in
user.login_failed — a sign-in attempt failed
mfa.enrolled — a user enrolled an MFA method

The wildcard audit.* subscribes to all audit events via webhooks.

Authentication events

`user.login`

A user successfully signed in.

{
  "type": "user.login",
  "actor": { "id": "usr_01H...", "email": "alice@example.com", "type": "user" },
  "metadata": {
    "auth_method": "email_password",   // email_password | magic_link | oauth | sso | api_key
    "mfa_used": true,
    "mfa_method": "totp",              // totp | webauthn | backup_code | null
    "session_id": "sess_01H...",
    "oauth_provider": null             // google | github | etc. (when auth_method = oauth)
  }
}

`user.login_failed`

A sign-in attempt failed.

{
  "type": "user.login_failed",
  "actor": { "email": "alice@example.com", "type": "anonymous" },
  "metadata": {
    "reason": "invalid_password",      // invalid_password | user_not_found | account_disabled
                                       // | mfa_required | mfa_failed | rate_limited
    "auth_method": "email_password",
    "attempt_count": 3
  }
}

`user.logout`

A user signed out.

{
  "type": "user.logout",
  "actor": { "id": "usr_01H...", "type": "user" },
  "metadata": {
    "session_id": "sess_01H...",
    "logout_type": "explicit"          // explicit | session_expired | revoked
  }
}

`user.token_refreshed`

A refresh token was used to obtain a new access token.

`user.session_revoked`

A session was revoked (by the user or an admin).

{
  "type": "user.session_revoked",
  "actor": { "id": "adm_01H...", "type": "admin" },
  "resource": { "id": "sess_01H...", "type": "session" },
  "metadata": {
    "reason": "admin_revocation",       // admin_revocation | user_signed_out | all_sessions
    "affected_user_id": "usr_01H..."
  }
}

User management events

`user.created`

A new user account was created.

{
  "type": "user.created",
  "actor": { "id": "usr_01H...", "type": "user" },  // or admin
  "resource": { "id": "usr_01H...", "type": "user" },
  "metadata": {
    "signup_method": "email_password",  // email_password | magic_link | oauth | invited | admin
    "email_verified": false
  }
}

`user.updated`

A user's profile was updated.

{
  "type": "user.updated",
  "metadata": {
    "fields_changed": ["display_name", "avatar_url"]
  }
}

`user.email_changed`

A user's email address was changed.

{
  "type": "user.email_changed",
  "metadata": {
    "old_email": "alice@example.com",
    "new_email": "alice@newdomain.com",
    "verification_required": true
  }
}

`user.email_verified`

A user verified their email address.

`user.password_changed`

A user changed their password.

{
  "type": "user.password_changed",
  "metadata": {
    "initiated_by": "user",            // user | admin | password_reset
    "reset_token_used": false
  }
}

`user.password_reset_requested`

A password reset email was requested.

`user.disabled`

A user account was disabled.

`user.enabled`

A disabled user account was re-enabled.

`user.deleted`

A user account was deleted.

MFA events

`mfa.enrolled`

A user enrolled an MFA method.

{
  "type": "mfa.enrolled",
  "metadata": {
    "method": "totp",                  // totp | webauthn | backup_codes
    "device_name": "iPhone 15"         // for webauthn
  }
}

`mfa.removed`

A user removed an MFA method.

`mfa.challenged`

An MFA challenge was presented during login.

`mfa.challenge_failed`

An MFA challenge failed.

{
  "type": "mfa.challenge_failed",
  "metadata": {
    "method": "totp",
    "reason": "invalid_code",          // invalid_code | expired | rate_limited
    "attempt_count": 2
  }
}

`mfa.backup_codes_generated`

Backup codes were generated or regenerated.

`mfa.backup_code_used`

A backup code was used for authentication.

API key events

`api_key.created`

An API key was created.

{
  "type": "api_key.created",
  "metadata": {
    "key_id": "key_01H...",
    "name": "CI/CD Pipeline",
    "scopes": ["users:read", "tenants:read"],
    "expires_at": "2025-01-01T00:00:00Z"
  }
}

`api_key.rotated`

An API key was rotated (old key revoked, new key issued).

`api_key.revoked`

An API key was revoked.

`api_key.used`

An API key was used to authenticate a request. (Logged at a sampled rate to avoid high volume.)

Tenant events

`tenant.created`

A new tenant was created.

`tenant.updated`

A tenant's settings were changed.

{
  "type": "tenant.updated",
  "metadata": {
    "fields_changed": ["allowed_auth_methods", "mfa_required"]
  }
}

`tenant.deleted`

A tenant was deleted.

Organization events

`org.created` / `org.updated` / `org.deleted`

Organization lifecycle events.

`org.member_added`

A user was added to an organization.

{
  "type": "org.member_added",
  "metadata": {
    "org_id": "org_01H...",
    "added_user_id": "usr_01H...",
    "role": "member",
    "invited_by": "usr_01H..."
  }
}