The Multi-Factor Auth card under Application → Authentication sets the second factor users present after their primary credential. Enabling MFA is the single biggest improvement you can make to account security — phishing-resistant where the second factor is an authenticator, even when passwords get phished.
MFA is off entirely. Users cannot enroll, cannot present a second factor.
optional
Users can enroll on their own, from their profile page. Sign-in skips MFA for users who haven't enrolled.
required
Every user must enroll within the grace period. Sign-in always asks for the second factor (subject to "remember this device").
Most B2B apps want optional for early-stage and required once they've trained users. Switching from optional to required starts the grace-period countdown for every existing user who hasn't enrolled yet.
allowedMethods is the menu of factors a user can choose from. primaryMethod is the default that's offered first.
Method
What it is
totp
Time-based one-time password. Works with any TOTP authenticator app. Default and recommended.
sms
Six-digit code texted to the user's phone. Only enable if your audience can't or won't use a TOTP app.
whatsapp
Same code, delivered over WhatsApp. Useful in regions where WhatsApp is the default communication channel.
TOTP is the strongest of the three — codes are generated locally on the user's device and don't traverse the network, so they can't be SIM-swapped or intercepted.
When a user clicks Trust this device after presenting their second factor, Authaz issues a device-bound token that suppresses the MFA prompt on that device for rememberDeviceDurationDays (default: 30).
Setting
What it controls
rememberDeviceDurationDays
How long a trusted device skips MFA. 0 disables the feature entirely.
maxTrustedDevices
Cap per user. Older devices fall off the list as new ones are added.
The trusted-device token is bound to the browser fingerprint + cookie — copying it to a different device won't bypass MFA.
When mode is required and a user hasn't enrolled yet, they're given gracePeriodDays (default: 7) to set up MFA. During that window they can sign in normally; on each login Universal Login nudges them with a banner. After the window expires, they cannot sign in until they enroll.
Set gracePeriodDays: 0 for a hard cutover — useful only if you've already announced the change and given users time to prepare.
curl -X POST https://your-app.authaz.io/api/v1/users/{userId}/mfa/reset \ -H "X-API-Key: $AUTHAZ_API_KEY"
This wipes the user's existing TOTP secret and invalidates outstanding recovery codes. On their next sign-in, Universal Login walks them through enrollment again. An audit-log entry is recorded with the admin who performed the reset.
If the user still has at least one recovery code, they can use it on the MFA prompt instead of asking an admin.
