Skip to main content

Documentation Index

Fetch the complete documentation index at: https://stytch.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

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.

​
Learn more

MFA guide

Comprehensive MFA documentation

Configure auth methods

Set organization MFA policies