Enrolling a Member in MFA

Stytch enables Members to individually enroll in Multi-Factor Authentication for a more secure login experience. Once enrolled, the Member will always be prompted to authenticate with a primary and secondary factor in order to log in and create a Session.

In this guide, you'll learn how to enroll an individual Member in MFA using SMS OTP. By the end, you'll have:

• Authenticated with SMS OTP.
• Enrolled a Member in MFA.

Before you start

If you want to enforce MFA at the Organization-level for all Members, check out the guide for managing Organization settings.

In order to complete this guide, you'll need the following:

• A Stytch B2B project. If you don't have one already, in the Dashboard, click on your existing project name in the top left corner of the Dashboard, click Create a new project, and then select B2B Authentication.
• The project Test environment's project_id and secret from the API keys section. You'll need to pass these values into the Authorization request header for every Stytch API call.
• An Organization with active Members.

Step 1: Authenticate a Member

In order to enroll in MFA, a Member needs exactly one of the following values:

• A session_jwt for an active Session.
• A session_token for an active Session.
• An intermediate_session_token returned from a Discovery flow or MFA flow.

These values are created by successfully authenticating a Member with endpoints such as:

• Authenticate EML endpoint
• Authenticate Discovery EML endpoint
• Authenticate Password endpoint
• Authenticate OAuth endpoint
• Authenticate SSO endpoint

You can check out guides for EML, OAuth, or SSO to learn how to authenticate a Member with your preferred auth method.

Step 2: Call the Send OTP SMS endpoint

Once you've authenticated a Member, call the Send OTP SMS endpoint with the following parameters:

curl --request POST \
	--url https://test.stytch.com/v1/b2b/otps/sms/send \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": {ORGANIZATION_ID},
		"member_id": {MEMBER_ID},
		"mfa_phone_number": {MEMBER_PHONE_NUMBER}
	}'

Make sure the mfa_phone_number is in the E.164 format, e.g. “+14155551234”.

After a successful API call, the provided phone number will receive an SMS with an OTP code.

Step 3: Authenticate the OTP and opt to enroll in MFA

Choose one of the values specified in Step 1: session_jwt, session_token, or intermediate_session_token. Providing more than one value in the ensuing API request will result in an error.

Call the Authenticate OTP SMS endpoint with the following parameters:

curl --request POST \
	--url https://test.stytch.com/v1/b2b/otps/sms/authenticate \
	-u 'PROJECT_ID:SECRET' \
	-H 'Content-Type: application/json' \
	-d '{
		"organization_id": {ORGANIZATION_ID},
		"member_id": {MEMBER_ID},
		"code": {SMS_OTP_CODE},
		"session_token": {SESION_TOKEN},
  // or "session_jwt": {SESSION_JWT},
  // or "intermediate_session_jwt": {INTERMEDIATE_SESSION_JWT},
		"set_mfa_enrollment": "enroll" 
	}'

The response will look like this:

{
	"member": {
		"email_address": "{MEMBER_EMAIL_ADDRESS}",
		"email_address_verified": true,
		"member_id": "member-test-dd178c82-0c72-4f3e-8623-708aa599ce7f",
		"mfa_enrolled": true,
		"mfa_phone_number": "{MEMBER_PHONE_NUMBER}",
		"mfa_phone_number_verified": true,
        ...
	},
	"member_session": {...},
	"organization": {...},
	"request_id": "request-id-test-56afb9e7-e26b-418f-b82e-0c0d525ba875",
	"session_jwt": "eyJhbGciOiJSUzI1...",
	"session_token": "oFRmDIMpP-4xVHcJq1Rue4IJYn1ygGZfTjHtHyfzlyPZ",
	"status_code": 200
}

After a successful API call:

• The Member will be enrolled in MFA.
• The Member will be required to complete the MFA flow in order to log in and create a Session.
• The Member record will be updated with a populated mfa_phone_number used in the SMS OTP.
• The Member record will have mfa_phone_number_verified and mfa_enrolled set to true.

Unenrolling a Member from MFA

To unenroll from MFA, repeat all previous steps but set set_mfa_enrollment to unenroll in Step 3 when authenticating the SMS OTP.

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.