Skip to main content

Multi-Factor Authentication (MFA)

Multi-factor authentication (MFA) adds an extra layer of security by requiring users to provide two or more verification factors to access their accounts. Users must verify their identity using one of the supported authentication methods after entering login credentials (email/phone/username + password).

Supported MFA Methods in LoginRadius

  • SMS OTP
  • Time-Based OTP (TOTP) via Authenticator App
  • Email OTP
  • Security Questions
  • Push Notification
  • Passkey
  • Backup Codes
  • Duo Authentication

Refer to the MFA documentation for the configuration steps for these methods.

MFA Workflow Scenarios

Case 1: MFA Required, No Authenticator Configured

When a user logs in with valid credentials but has no authenticators configured, all available MFA options will be presented:

a) Email OTP

  • If only one email is linked, the OTP input is shown.
  • If multiple emails exist, the user selects from a dropdown.
  • Includes Resend Verification Code and Back options.

b) Security Questions

  • If not set, the user is prompted to configure questions first.
  • If set, the user answers them to continue.
  • If forgotten, the "Set Security Questions" button allows reconfiguration.

c) Google Authenticator

  • A QR code is displayed to configure the TOTP-based authenticator.

d) SMS OTP

  • An OTP is sent for verification after verifying or updating the phone number.

Case 2: MFA Required, Authenticator Already Configured

If at least one MFA method is configured, the primary authenticator is shown with an option:

  • Try Another Way to Sign In — Displays the Backup Code login method.

Case 3: MFA Required, Multiple Authenticators Configured

If Email OTP, SMS OTP, and Security Questions are already configured:

  • Users can disable any authenticator unless only one is active (to maintain the MFA requirement).

Implementing MFA via APIs

1. Enable MFA in Admin Console

Select desired authentication methods via the LoginRadius Console.

2. First-Factor Authentication

Use one of the following APIs to initiate login:

a) MFA Email Login

POST /identity/v2/auth/login/2fa

Required Params:

  • apikey, email, password

Optional Params:

  • loginurl, emailtemplate, emailtemplate2FA, g-recaptcha-response, securityanswer, duoredirecturi

b) MFA Username Login

Same endpoint, use username instead of email.

c) MFA Phone Login

Same endpoint, use phone instead of email.

3. Handle Second-Factor Challenge

Successful first-factor login returns:

  • SecondFactorAuthenticationToken
  • Expiry time
  • Available authenticators (email, SMS, TOTP, etc.)

Example Response (Trimmed)

{
  "SecondFactorAuthentication": {
    "SecondFactorAuthenticationToken": "b1f...e6f4",
    "ExpireIn": "2021-04-06T08:36:53.300Z",
    "QRCode": "https://chart.googleapis.com/chart?...",
    "ManualEntryCode": "HBRWENL...",
    "Email": ["x**z@e****le.c*m"],
    "SecurityQuestions": [{ "QuestionId": "<id>", "Question": "<text>" }]
  }
}

4. Verify Second-Factor Authenticator

Use the appropriate API for the selected method. For more information on the respective API, follow the API documentation of the desired method:

Example: Validate SMS OTP

PUT /identity/v2/auth/login/2fa/verification/otp

Required Params:

  • apikey, secondfactorauthenticationtoken, otp

Lockout Scenarios During MFA

Repeated failures in verifying the second factor trigger a lockout, based on brute force protection settings:

Lockout TypeBehavior
SuspendTemporarily locks the account. Users must wait and log in again after the suspension period.
CaptchaPrompts reCAPTCHA verification on login retry.
Security QuestionsRequires answering security questions to unlock.
BlockThe account is locked permanently until an administrator manually unblocks it.

Note: Users can fall back on Backup Codes if no unlock method works.

Best Practices

  • Ensure users always have at least one MFA method configured.
  • Encourage users to set up Backup Codes if their primary factor is inaccessible.
  • Monitor lockout events using LoginRadius Events & Logs.
  • Use REST APIs for granular control and automation across MFA operations.