Server Events

Register hooks with @auth.on("event_name") or auth.add_hook("event_name", callback).

---

user_created

Fired when a new user is created (via signup, OAuth, or create_user()).

Field	Type
user_id	UUID
email	str
name	str | None
provider	str — "email", "google", "github", "magic_link", "email_otp", or any generic provider name
timestamp	datetime

login

Fired on successful authentication.

Field	Type
user_id	UUID
email	str
provider	str
ip_address	str | None
user_agent	str | None
timestamp	datetime

login_failed

Fired when login fails.

Field	Type
email	str
reason	str — e.g., "invalid_credentials", "user_banned"
ip_address	str | None
user_agent	str | None
timestamp	datetime

logout

Fired when a user logs out.

Field	Type
user_id	UUID | None
timestamp	datetime

token_refreshed

Fired when a refresh token is used to get new tokens.

Field	Type
user_id	UUID
ip_address	str | None
user_agent	str | None
timestamp	datetime

oauth_link

Fired when an OAuth account is linked to an existing user (email match).

Field	Type
user_id	UUID
email	str
provider	str
timestamp	datetime

role_added

Fired when a role is assigned.

Field	Type
user_id	UUID
role	str
timestamp	datetime

role_removed

Fired when a role is removed.

Field	Type
user_id	UUID
role	str
timestamp	datetime

user_updated

Fired when a user’s profile fields are updated via update_user().

Field	Type
user_id	UUID
fields	list[str] — names of updated fields (e.g., ["name", "phone"])
timestamp	datetime

user_banned

Fired when a user is banned.

Field	Type
user_id	UUID
timestamp	datetime

user_unbanned

Fired when a user is unbanned.

Field	Type
user_id	UUID
timestamp	datetime

session_revoked

Fired when sessions are revoked.

Field	Type
user_id	UUID
session_id	UUID | None — None if revoke_all
revoke_all	bool
timestamp	datetime

key_rotated

Fired when a new signing key is created.

Field	Type
old_kid	str
new_kid	str
timestamp	datetime

password_reset_requested

Fired when create_password_reset_token() is called for a valid user.

Field	Type
user_id	UUID
email	str
timestamp	datetime

password_reset

Fired when a password is successfully reset via token.

Field	Type
user_id	UUID
timestamp	datetime

password_changed

Fired when a password is changed via change_password().

Field	Type
user_id	UUID
timestamp	datetime

password_set

Fired when a passwordless user sets their initial password via set_password().

Field	Type
user_id	UUID
timestamp	datetime

email_verification_requested

Fired when create_email_verification_token() is called for a valid user.

Field	Type
user_id	UUID
email	str
token	str — raw token for delivery
timestamp	datetime

email_verified

Fired when a user’s email is successfully verified — via verify_email(), magic link, email OTP, or programmatically via create_user(email_verified=True) / update_user(email_verified=True). Not fired if the user is already verified.

Field	Type
user_id	UUID
email	str
timestamp	datetime

magic_link_requested

Fired when create_magic_link_token() is called for a valid user.

Field	Type
user_id	UUID
email	str
token	str — raw token for delivery
timestamp	datetime

magic_link_login

Fired when a user logs in via magic link.

Field	Type
user_id	UUID
email	str
timestamp	datetime

email_otp_requested

Fired when create_email_otp() is called for a valid user.

Field	Type
user_id	UUID
email	str
code	str — raw 6-digit code for delivery
timestamp	datetime

email_otp_login

Fired when a user logs in via email OTP.

Field	Type
user_id	UUID
email	str
timestamp	datetime

user_deleted

Fired when a user is deleted via delete_user().

Field	Type
user_id	UUID
email	str
timestamp	datetime

mfa_enabled

Fired when a user successfully enables TOTP MFA.

Field	Type
user_id	UUID
email	str
timestamp	datetime

mfa_disabled

Fired when MFA is disabled — by the user (with a code) or by an admin override.

Field	Type
user_id	UUID
email	str
timestamp	datetime

mfa_login

Fired when the MFA step of a login is completed successfully.

Field	Type
user_id	UUID
email	str
ip_address	str | None
timestamp	datetime

mfa_failed

Fired when a TOTP or backup code is rejected during MFA verification. Good target for account lockout logic.

Field	Type
user_id	UUID
email	str
ip_address	str | None
timestamp	datetime

backup_code_used

Fired when a backup code is consumed during login.

Field	Type
user_id	UUID
email	str
timestamp	datetime

backup_codes_regenerated

Fired when a user regenerates their backup codes.

Field	Type
user_id	UUID
email	str
timestamp	datetime

rate_limit_exceeded

Fired when a request is rejected due to rate limiting.

Field	Type
endpoint	str — e.g., "login", "signup", "refresh"
ip_address	str | None
email	str | None — present for email-based limits
limit	str — the limit that was exceeded (e.g., "5/min")
key_type	str — "ip" or "email"
timestamp	datetime