Authentication Method

The optional authentication_method object can be used for any of the following events:

  • $registration – what method was used to create the user account
  • $login – what method was used to create a new authentication session
  • $challenge – what method was requested from or resolved by the users as additional verification

By sending this information, not only does it provide valuable insight during fraud investigations when used to filter down the dataset as well as configuring policies, but it also helps improve Castle's risk models.

Field

Type

Description

type

$authenticator, $biometrics, $email, $password, $phone, $push, $security_key, $social, $sso

See below for detailed explanation

variant

String

Optional description of the method variant, e.g. facebook when type is $social, or sms for $phone

email

String (e-mail format required)

E-mail of the user account. Only applicable with the type is $email

phone

String (E.164 format required)

Phone number of the user account. Only applicable when the type is $phone

As outlined in the table above, for the $email and $phone types you can also send the email address or phone number used in the authentication, especially for when it's different to what's registered on the user account.

Authentication types

Detailed description of the available options for the type parameter

Type

Description

$authenticator

Google Authenticator, or any other OTP app

$biometrics

Apple FaceID/TouchID, Microsoft Hello, etc

$email

Email confirmation/magic link or PIN code

$password

Standard password entry, combined with email, phone, or username

$phone

Phone confirmation/magic link or PIN code

$push

Mobile push notification

$security_key

Yubikey, Google Titan, etc

$social

Social sign-in with Google, Facebook, Apple, etc

$sso

SAML, e.g. Okta or Rippling

Example

{
 // ...
  "authentication_method": {
    "type": "$phone",
    "phone": "+14152549324",
    "variant": "sms"
  }
}

Did this page help you?