MFA overview - Stytch Docs

Multi-factor authentication (MFA) adds an additional security layer by requiring members to verify their identity with a second factor after their primary authentication. Stytch supports SMS OTP and TOTP authenticator apps.

When MFA is required

MFA can be enforced at the organization level using the mfa_policy setting:

REQUIRED_FOR_ALL - All members must complete MFA after primary authentication
OPTIONAL - Members can optionally enroll in MFA for their account

When MFA is required, authentication endpoints return member_authenticated: false and an intermediate_session_token. The member must complete an MFA challenge before receiving a full session. Organizations can also restrict which MFA methods are allowed using mfa_methods and allowed_mfa_methods settings. See the Update Organization endpoint for configuration details.

MFA authentication flow

SMS OTP
TOTP

Send a one-time passcode via SMS to the member’s enrolled phone number.Send SMS OTP:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/otps/sms/send \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "mfa_phone_number": "+15555555555"
  }'

Authenticate OTP with the Authenticate SMS OTP endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/otps/sms/authenticate \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "code": "123456",
    "intermediate_session_token": "intermediate_session_token_...",
    "session_duration_minutes": 60
  }'

Returns a full session upon successful verification.

After a successful primary authentication (email magic link, SSO, etc.), an SMS OTP is automatically sent if the member has a phone number enrolled. This endpoint is primarily for resending OTPs.

Authenticate using a time-based one-time passcode from an authenticator app like Google Authenticator or Authy.Create TOTP registration with the Create TOTP endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/totp \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f"
  }'

Response:

{
  "status_code": 200,
  "totp_id": "totp-test-...",
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,...",
  "recovery_codes": ["code1", "code2", "..."]
}

Display the QR code for the member to scan with their authenticator app.Authenticate TOTP with the Authenticate TOTP endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/b2b/totp/authenticate \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "code": "123456",
    "intermediate_session_token": "intermediate_session_token_...",
    "session_duration_minutes": 60
  }'

Returns a full session upon successful verification.

Learn more

MFA guide

Comprehensive MFA documentation

Configure auth methods

Set organization MFA policies

​When MFA is required

​MFA authentication flow

​Learn more

MFA guide

Configure auth methods

When MFA is required

MFA authentication flow

Learn more