> ## 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.

# MFA overview

> Add multi-factor authentication with SMS OTP or TOTP using the Stytch API

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](/docs/api-reference/b2b/api/organizations/update-organization) endpoint for configuration details.

## MFA authentication flow

<Tabs>
  <Tab title="SMS OTP" icon="message-square">
    Send a one-time passcode via SMS to the member's enrolled phone number.

    **Send SMS OTP:**

    ```bash theme={null}
    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](/docs/api-reference/b2b/api/mfa/otp/authenticate-sms-otp) endpoint:**

    ```bash theme={null}
    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.

    <Note>
      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.
    </Note>
  </Tab>

  <Tab title="TOTP" icon="smartphone">
    Authenticate using a time-based one-time passcode from an authenticator app like Google Authenticator or Authy.

    **Create TOTP registration with the [Create TOTP](/docs/api-reference/b2b/api/mfa/totp/create-totp) endpoint:**

    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "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](/docs/api-reference/b2b/api/mfa/totp/authenticate-totp) endpoint:**

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## Learn more

<CardGroup cols={2}>
  <Card title="MFA guide" icon="book" href="/docs/multi-tenant-auth/authentication/mfa/overview">
    Comprehensive MFA documentation
  </Card>

  <Card title="Configure auth methods" icon="settings" href="/docs/multi-tenant-auth/enterprise-ready/org-management/configure-auth-methods">
    Set organization MFA policies
  </Card>
</CardGroup>