Use SMS OTP for MFA login

Stytch's Multi-Factor Authentication is a multi-step login process that enforces the use of a secondary factor like SMS OTP.

Organizations can require MFA for all of their Members, and if required all members will be forced to enroll in and perform MFA before logging into the Organization.

If you are using our Pre-built UI this flow will be handled for you automatically. See the UI Config reference for how to specify MFA options and ordering

If you are doing a headless frontend or backend integration you will need to do some handling to prompt the user for their MFA method and submit to Stytch.

This guide assumes that you have already built out primary organization authentication with one of the following:

• Email Magic Links
• OAuth
• SSO

If you haven't done that already, follow those quickstarts and then come back to setting up MFA!

Update your Organization's MFA Policy to REQUIRED_FOR_ALL either through the dashboard or by calling the Update Organization endpoint.

After calling the authenticate() method for the primary auth flow you've chosen, you will get back a response that indicates that the user needs to perform MFA before being granted a Session for the Organization through the following values:

• member_authenticated is false. At this point, only the primary factor has been completed. The Member is not fully authenticated yet.
• The mfa_required object will contain additional information (like a phone number) if the Member has completed the MFA flow before.

{
	"intermediate_session_token": "oNJB3foIA79dn_uNVMNghG_MGkKSLHnR65NsKXv0gZzY",
    "mfa_required": {
		"member_options": {
			"mfa_phone": "",
			"totp_registration_id": ""
		},
		"secondary_auth_initiated": null
	},
	"member_authenticated": false,
    ...
}

If you are using a backend integration, make sure to store the intermediate_session_token (in cookies or elsewhere). This is automatically taken care of for you when using the frontend SDKs.

Taking the MemberID and OrganizationID call the Send OTP SMS endpoint. If the Member is already enrolled in MFA with SMS, this will automatically use their MFA phone number. If they are not enrolled you will need to specify the mfa_phone_number in the E.164 format, e.g. “+14155551234”.

Surface a way for the user to input the OTP they received, and then call the Authenticate OTP SMS endpoint with the following values:

• organization_id
• member_id
• code (the OTP provided by the user)
• intermediate_session_token (from the initial authenticate response)

After a successful API call, Stytch will issue a Session for the Member indicating that they are properly authenticated.

Build a user interface that allows end users to log in with MFA using EML as a primary factor and SMS OTP as a secondary factor.

Clone our B2B Next.js example app for helpful templates that can get you started quickly. Also check out our interactive B2B demo app to see the app in action.