Skip to main content

​
What is multi-factor authentication?

Multi-factor authentication (MFA) is a mechanism that requries users to provide two or more authentication factors to verify their identity.

​
What happens

If a user is required to complete multi-factor authentication, a intermediate_session_token is returned instead of a session_token in response to the initial authentication request, and an OTP code is automatically sent to the user’s phone number (if they are enrolled in SMS OTP). The following values will also be set in the authentication response:
​
member_authenticated
boolean
Value will be false.
​
primary_required
object | null
Value may be non-null if the member also needs to complete a primary step-up authentication flow. If this value is non-null, the primary step-up flow should be completed before proceeding to MFA completion.
​
mfa_required
object | null
Value will be non-null and will contain which form of MFA is required to be completed.

​
Sample response

Response 200
{
    "intermediate_session_token": "Fxq0E...",
    "member": {
        // Full Member object
    },
    "member_authenticated": false,
    "member_id": "member-...",
    "member_session": null,
    "method_id": "member-email-...",
    "mfa_required": {
        "member_options": {
            "mfa_phone_number": "XXXXXXX1234",
            "totp_registration_id": ""
        },
        "secondary_auth_initiated": "sms_otp"
    },
    "organization": {
        // Full Organization object
    },
    "organization_id": "organization-...",
    "request_id": "request-id-...",
    "reset_sessions": false,
    "session_jwt": "",
    "session_token": "",
    "status_code": 200
}

​
Next steps

At this point, you will need to prompt the user to completed the required MFA step. See our guide on how to implement multi-factor authentication:

Add MFA to a custom auth flow

Guide to integrating multi-factor into your own authentication flow.