New

If you signed up before June 3, 2021, see the migration guide to learn about the recent API changes.

Events

Event names that are officially supported by Castle

List of recognized events

The events below are officially supported as “recognized” events. Custom events may be used for special circumstances, but we strongly recommend using events from this list.

Filter and Risk

NameDescription
$loginAn user logging into your application
$registrationA visitor signing up to become a user of your application
$profile_updateAn user updating their email, password, name, or phone number.
$transactionA user transacting, e.g. a withdrawal, transfer, or purchase.
$password_reset_requestA visitor initiating a password reset flow, i.e. not actually resetting the password (yet).

Log

NameDescription
$loginParticularly used with status: "$failed" to record when a user failed to log in due to invalid credentials.`

Track

NameDescription
$password_reset.succeededThe user completed all of the steps in the password reset process and the password was successfully reset. Password resets do not required knowledge of the current password.
$password_reset.failedUse to record when a user failed to reset their password.
$password_reset_request.failedThe user failed to request a password reset.
$incident.mitigatedUser account has been reset.
$review.escalatedUser confirmed malicious activity.
$challenge.requestedRecord when a user is prompted with additional verification, such as two-factor authentication or a captcha.
$challenge.succeededRecord when additional verification was successful.
$challenge.failedRecord when additional verification failed.
$session.extendedRecord when a user session is extended, or use any time you want to re-authenticate a user mid-session.

Custom events

You can use any custom string as event value in order to analyze specific business logic that’s not represented by Castle’s recognized events. The only requirement is that the string cannot start with with reserved prefix $.

List of recognized events for Authenticate (legacy)

The events below are officially supported as “recognized” events. Custom events may be used for special circumstances, but we strongly recommend using events from this list.

NameDescription
$login.succeededRecord when a user succesfully logs in / enters valid credentials.
$login.failedRecord when a user failed to log in due to invalid credentials.
$login.attemptedRecord when a login is attempted, but credential validation has not yet occured.
$logout.succeededRecord when a user logs out.
$profile_update.succeededRecord when a user updated their profile (including password, email, phone, etc).
$profile_update.failedRecord errors when updating profile.
$profile_update.attemptedRecord when a user profile update is being attempted.
$registration.succeededCapture account creation, both when a user signs up as well as when created manually by an administrator.
$registration.failedRecord when an account failed to be created.
$registration.attemptedRecord when a registration is being attempted, but before it has been validated and account creation occurs.
$password_reset.succeededThe user completed all of the steps in the password reset process and the password was successfully reset. Password resets do not required knowledge of the current password.
$password_reset.failedUse to record when a user failed to reset their password.
$password_reset_request.attemptedThe user attempted to request a password reset.
$password_reset_request.succeededThe user successfully requested a password reset.
$password_reset_request.failedThe user failed to request a password reset.
$incident.mitigatedUser account has been reset.
$review.escalatedUser confirmed malicious activity.
$review.resolvedUser confirmed safe activity. (deprecated)
$challenge.requestedRecord when a user is prompted with additional verification, such as two-factor authentication or a captcha.
$challenge.succeededRecord when additional verification was successful.
$challenge.failedRecord when additional verification failed.
$transaction.attemptedRecord when a user attempts an in-app transaction, such as a purchase or withdrawal.
$session.extendedRecord when a user session is extended, or use any time you want to re-authenticate a user mid-session.