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

# Adding MFA to a custom auth flow

> Integrate MFA with Stytch's headless or backend SDKs for complete control over your authentication flow.

## Prerequisites

Before you can add MFA to a custom auth flow, you'll need to complete the following steps:

**1. Build out primary authentication**

Before integrating MFA, you need to already have a **primary authentication flow** built out. You can do so by following one of the integration guides:

> [card] [Email Magic Links](https://stytch.com/docs/multi-tenant-auth/authentication/magic-links/overview.md)

> [card] [OAuth](https://stytch.com/docs/multi-tenant-auth/authentication/oauth/overview.md)

> [card] [SSO](https://stytch.com/docs/multi-tenant-auth/authentication/sso/overview.md)

**2. Configure enforced MFA for an Organization**

To configure MFA, you'll need to first toggle on "Require MFA" for at least one Organization in the [Stytch Dashboard](https://stytch.com/dashboard/organizations), or call the [Update Organization API](https://stytch.com/docs/api-reference/b2b/api/organizations/update-organization.md) with `mfa_policy` set to `REQUIRED_FOR_ALL`.

Each Organization can specify which `mfa_methods` are allowed for Members in their Organization: either `ALL_ALLOWED` or `RESTRICTED`. If `RESTRICTED`, Members can only use MFA methods specified in the `allowed_mfa_methods` array.

For example, if an Organization requires Members to use TOTP MFA:

```json theme={null}
{
    "mfa_policy": "REQUIRED_FOR_ALL",
    "mfa_methods": "RESTRICTED",
    // Optional, not enforced if mfa_methods is ALL_ALLOWED
    "allowed_mfa_methods": ["totp"]
}
```

## Integrating MFA

Stytch's headless and backend SDKs provide a flexible way to integrate MFA into your authentication flow.

> [tab] Headless frontend SDK
>
> > [tab] First-time enrollment
> >
> > ### Required MFA enrollment
> >
> > When an Organization's MFA policy is `REQUIRED_FOR_ALL` but the Member is not currently enrolled in MFA, you'll need to handle MFA enrollment after primary authentication.
> >
> > **1. Detect when MFA enrollment required**
> >
> > The following authentication methods will return a Member Session if the Member is not enrolled in MFA OR an `intermediate_session_token` and an `mfa_required` object that indicates MFA is required in order to be granted a Session for the Organization:
> >
> > * [sso.authenticate()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/sso/authenticate.md)
> > * [oauth.authenticate()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/oauth/discovery-authenticate.md)
> > * [magicLinks.authenticate()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/email-magic-links/authenticate-discovery-magic-link.md)
> > * [passwords.authenticate()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/passwords/authenticate.md)
> > * [discovery.intermediateSessions.exchange()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/discovery/exchange-intermediate-session.md)
> > * [passwords.resetByEmail()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/passwords/reset-by-email.md)
> > * [passwords.resetByExistingPassword()](https://stytch.com/docs/api-reference/b2b/frontend-sdks/react/methods/passwords/reset-by-existing-password.md)
> >
> > If the Member is not yet enrolled in MFA, the response will look as follows:
> >
> > ```json theme={null}
> > {
> >     "intermediate_session_token": "oNJB3foIA79dn_uNVMNghG_MGkKSLHnR65NsKXv0gZzY",
> >     "mfa_required": {
> >         "member_options": null,
> >         "secondary_auth_initiated": null
> >     },
> >     "member_authenticated": false,
> >     "organization": {
> >         "mfa_methods": "REQUIRED_FOR_ALL",
> >         "allowed_mfa_methods": ["sms_otp", "totp"]
> >     }
> >     ...
> > }
> > ```
> >
> > Indicating that `member_authenticated: false` due to `mfa_required` -- but no `member_options` are present. The Stytch SDK will automatically store the `intermediate_session_token` and handle passing that with subsequent calls to tie the user's primary and secondary authentication together.
> >
> > For the primary authentication endpoint(s) you've already integrated add handling to detect when MFA enrollment is required by checking to see if the `organization.mfa_methods` is `ALL_ALLOWED` or `RESTRICTED`. If `RESTRICTED` use the `organization.allowed_mfa_methods` to surface only allowed MFA methods to the user.
> >
> > Check the `organization.allowed_mfa_methods` and based on the available options, prompt the user to enroll in MFA.
> >
> > **2. Start MFA enrollment**
> >
> > > [tab] SMS OTP
> > >
> > > For SMS MFA, prompt the user for their phone number and call the SMS Send method with the number. Make sure the `mfa_phone_number` is in the E.164 format, e.g. "+14155551234".
> > >
> > > ```jsx React icon=react theme={null}
> > > import { useCallback, useState } from 'react';
> > > import { useStytchB2BClient } from '@stytch/react/b2b';
> > >
> > > export const SendOtp = () => {
> > >   const stytchClient = useStytchB2BClient();
> > >   const [phoneNumber, setPhoneNumber] = useState('');
> > >
> > >   const trigger = useCallback(() => {
> > >     stytchClient.otps.sms.send({
> > >       organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >       member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c2cfb6e1bd7d',
> > >       mfa_phone_number: phoneNumber,
> > >     });
> > >   }, [stytchClient, phoneNumber]);
> > >
> > >   return (
> > >     <div>
> > >       <input
> > >         type="tel"
> > >         placeholder="Enter phone number"
> > >         value={phoneNumber}
> > >         onChange={(e) => setPhoneNumber(e.target.value)}
> > >       />
> > >       <button onClick={trigger}>Send OTP</button>
> > >     </div>
> > >   );
> > > };
> > > ```
> > >
> > > ```html Vanilla JS icon=js theme={null}
> > > <form>
> > >   <input type="tel" id="phone-input" placeholder="Enter phone number" />
> > >   <button onclick="sendOtp()" type="submit">Send OTP</button>
> > > </form>
> > > <script>
> > >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> > >   const stytch = new StytchB2BHeadlessClient('STYTCH_PUBLIC_TOKEN');
> > >
> > >   const sendOtp = (e) => {
> > >     e.preventDefault();
> > >     stytch.otps.sms.send({
> > >       member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >       organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >       mfa_phone_number: document.getElementById('phone-input').value,
> > >     });
> > >   };
> > > </script>
> > > ```
> >
> > > [tab] TOTP
> > >
> > > For TOTP MFA, you'll first trigger the TOTP Create method, which will return a `qr_code` that you will surface to the end user to register their authenticator app.
> > >
> > > ```jsx React icon=react theme={null}
> > > import { useCallback } from 'react';
> > > import { useStytchB2BClient } from '@stytch/react/b2b';
> > >
> > > export const CreateTOTP = () => {
> > >   const stytchClient = useStytchB2BClient();
> > >
> > >   const trigger = useCallback(() => {
> > >     stytchClient.totp.create({ expiration_minutes: 60 });
> > >   }, [stytchClient]);
> > >
> > >   return <button onClick={trigger}>Create TOTP</button>;
> > > };
> > > ```
> > >
> > > ```html Vanilla JS icon=js theme={null}
> > > <form>
> > >   <button onclick="create()" type="submit">Create TOTP</button>
> > > </form>
> > > <script>
> > >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> > >   const stytch = new StytchB2BHeadlessClient('STYTCH_PUBLIC_TOKEN');
> > >
> > >   const create = (e) => {
> > >     e.preventDefault();
> > >     stytch.totp.create({
> > >       member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >       organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >       expiration_minutes: 60,
> > >     });
> > >   };
> > > </script>
> > > ```
> >
> > **3. Authenticate to complete enrollment**
> >
> > Prompt the user to input their OTP or TOTP code in order to complete the MFA enrollment and authenticate.
> >
> > > [tab] SMS OTP
> > >
> > > ```jsx React icon=react theme={null}
> > > import { useCallback, useState } from 'react';
> > > import { useStytchB2BClient } from '@stytch/react/b2b';
> > >
> > > export const Authenticate = () => {
> > >   const stytch = useStytchB2BClient();
> > >   const [code, setCode] = useState('');
> > >
> > >   const authenticate = useCallback(
> > >     (e) => {
> > >       e.preventDefault();
> > >       stytch.otps.sms.authenticate({
> > >         member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >         organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >         code: code,
> > >         session_duration_minutes: 60,
> > >       });
> > >     },
> > >     [stytch, code],
> > >   );
> > >
> > >   const handleChange = useCallback((e) => {
> > >     setCode(e.target.value);
> > >   }, []);
> > >
> > >   return (
> > >     <form>
> > >       <label htmlFor="otp-input">Enter code</label>
> > >       <input id="otp-input" autoComplete="one-time-code" inputMode="numeric" pattern="[0-9]*" onChange={handleChange} />
> > >       <button onClick={authenticate} type="submit">
> > >         Submit
> > >       </button>
> > >     </form>
> > >   );
> > > };
> > > ```
> > >
> > > ```html Vanilla JS icon=js theme={null}
> > > <form>
> > >   <label for="otp-input">Enter code</label>
> > >   <input id="otp-input" autocomplete="one-time-code" inputtype="numeric" pattern="[0-9]*"></input>
> > >   <button onclick="authenticate()" type="submit">Submit</button>
> > > </form>
> > > <script>
> > >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> > >   const stytch = new StytchB2BHeadlessClient('STYTCH_PUBLIC_TOKEN');
> > >
> > >   const authenticate = (e) => {
> > >     e.preventDefault();
> > >     stytch.otps.sms.authenticate({
> > >       member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >       organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >       code: document.getElementById('otp-input').value,
> > >       session_duration_minutes: 60,
> > >     });
> > >   };
> > > </script>
> > > ```
> >
> > > [tab] TOTP
> > >
> > > ```jsx React icon=react theme={null}
> > > import { useCallback, useState } from 'react';
> > > import { useStytchB2BClient } from '@stytch/react/b2b';
> > >
> > > export const Authenticate = () => {
> > >   const stytchClient = useStytchB2BClient();
> > >   const [totpCode, setTotpCode] = useState('');
> > >
> > >   const authenticate = useCallback(
> > >     (e) => {
> > >       e.preventDefault();
> > >       stytchClient.totp.authenticate({ code: totpCode, session_duration_minutes: 60 });
> > >     },
> > >     [stytchClient, totpCode],
> > >   );
> > >
> > >   const handleChange = useCallback((e) => {
> > >     setTotpCode(e.target.value);
> > >   }, []);
> > >
> > >   return (
> > >     <form>
> > >       <label htmlFor="totp-input">Enter code</label>
> > >       <input id="totp-input" value={totpCode} onChange={handleChange} />
> > >       <button onClick={authenticate} type="submit">
> > >         Submit
> > >       </button>
> > >     </form>
> > >   );
> > > };
> > > ```
> > >
> > > ```html Vanilla JS icon=js theme={null}
> > > <form>
> > >   <label for="totp-input">Enter code</label>
> > >   <input id="totp-input"></input>
> > >   <button onclick="authenticate()" type="submit">Submit</button>
> > > </form>
> > > <script>
> > >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> > >   const stytch = new StytchB2BHeadlessClient('STYTCH_PUBLIC_TOKEN');
> > >
> > >   const authenticate = (e) => {
> > >     e.preventDefault();
> > >     stytch.totp.authenticate({
> > >       member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >       organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >       code: document.getElementById('totp-input').value,
> > >       session_duration_minutes: 60,
> > >     });
> > >   };
> > > </script>
> > > ```
> >
> > **4. Test it out**
> >
> > Run your application and attempt to login to your Organization with the `REQUIRED_FOR_ALL` MFA policy to test out required enrollment in MFA.
>
> > [tab] Returning login
> >
> > ### Returning MFA authentication
> >
> > The flow for returning MFA authentication with a headless frontend integration is quite similar to the last steps of enrolling a Member in MFA for the first time.
> >
> > **1. Detect user's MFA options**
> >
> > When a Member is already enrolled in MFA, the response from the various `authenticate()` methods discussed in the "Required MFA Enrollment" section will include details on the MFA options they are enrolled in:
> >
> > ```json theme={null}
> > {
> >     "intermediate_session_token": "oNJB3foIA79dn_uNVMNghG_MGkKSLHnR65NsKXv0gZzY",
> >     "mfa_required": {
> >         "member_options": {
> >             "mfa_phone": "+14151112222",
> >             "totp_registration_id": "member-totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c"
> >         },
> >         "secondary_auth_initiated": "sms_otp"
> >     },
> >     "member_authenticated": false,
> >     ...
> > }
> > ```
> >
> > If a Member's `default_mfa_method` is SMS OTP, Stytch will automatically trigger the SMS Send when the user performs primary authentication for that Organization and will indicate this in the `secondary_auth_initiated` field.
> >
> > Check the `member_options` and surface the appropriate input to the Member to complete MFA.
> >
> > **2. Authenticate MFA**
> >
> > Similar to the last step of MFA enrollment, handle submission of the TOTP or OTP code in order to finish the MFA authentication and log the member in based on their default MFA method.
> >
> > > [tab] SMS OTP
> > >
> > > ```jsx React icon=react theme={null}
> > > import { useCallback, useState } from 'react';
> > > import { useStytchB2BClient } from '@stytch/react/b2b';
> > >
> > > export const Authenticate = () => {
> > >   const stytch = useStytchB2BClient();
> > >   const [code, setCode] = useState('');
> > >
> > >   const authenticate = useCallback(
> > >     (e) => {
> > >       e.preventDefault();
> > >       stytch.otps.sms.authenticate({
> > >         member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >         organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >         code: code,
> > >         session_duration_minutes: 60,
> > >       });
> > >     },
> > >     [stytch, code],
> > >   );
> > >
> > >   const handleChange = useCallback((e) => {
> > >     setCode(e.target.value);
> > >   }, []);
> > >
> > >   return (
> > >     <form>
> > >       <label htmlFor="otp-input">Enter code</label>
> > >       <input id="otp-input" autoComplete="one-time-code" inputMode="numeric" pattern="[0-9]*" onChange={handleChange} />
> > >       <button onClick={authenticate} type="submit">
> > >         Submit
> > >       </button>
> > >     </form>
> > >   );
> > > };
> > > ```
> > >
> > > ```html Vanilla JS icon=js theme={null}
> > > <form>
> > >   <label for="otp-input">Enter code</label>
> > >   <input id="otp-input" autocomplete="one-time-code" inputtype="numeric" pattern="[0-9]*"></input>
> > >   <button onclick="authenticate()" type="submit">Submit</button>
> > > </form>
> > > <script>
> > >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> > >   const stytch = new StytchB2BHeadlessClient('STYTCH_PUBLIC_TOKEN');
> > >
> > >   const authenticate = (e) => {
> > >     e.preventDefault();
> > >     stytch.otps.sms.authenticate({
> > >       member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >       organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >       code: document.getElementById('otp-input').value,
> > >       session_duration_minutes: 60,
> > >     });
> > >   };
> > > </script>
> > > ```
> >
> > > [tab] TOTP
> > >
> > > ```jsx React icon=react theme={null}
> > > import { useCallback, useState } from 'react';
> > > import { useStytchB2BClient } from '@stytch/react/b2b';
> > >
> > > export const Authenticate = () => {
> > >   const stytchClient = useStytchB2BClient();
> > >   const [totpCode, setTotpCode] = useState('');
> > >
> > >   const authenticate = useCallback(
> > >     (e) => {
> > >       e.preventDefault();
> > >       stytchClient.totp.authenticate({ code: totpCode, session_duration_minutes: 60 });
> > >     },
> > >     [stytchClient, totpCode],
> > >   );
> > >
> > >   const handleChange = useCallback((e) => {
> > >     setTotpCode(e.target.value);
> > >   }, []);
> > >
> > >   return (
> > >     <form>
> > >       <label htmlFor="totp-input">Enter code</label>
> > >       <input id="totp-input" value={totpCode} onChange={handleChange} />
> > >       <button onClick={authenticate} type="submit">
> > >         Submit
> > >       </button>
> > >     </form>
> > >   );
> > > };
> > > ```
> > >
> > > ```html Vanilla JS icon=js theme={null}
> > > <form>
> > >   <label for="totp-input">Enter code</label>
> > >   <input id="totp-input"></input>
> > >   <button onclick="authenticate()" type="submit">Submit</button>
> > > </form>
> > > <script>
> > >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> > >   const stytch = new StytchB2BHeadlessClient('STYTCH_PUBLIC_TOKEN');
> > >
> > >   const authenticate = (e) => {
> > >     e.preventDefault();
> > >     stytch.totp.authenticate({
> > >       member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >       organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >       code: document.getElementById('totp-input').value,
> > >       session_duration_minutes: 60,
> > >     });
> > >   };
> > > </script>
> > > ```
> >
> > **3. Test it out**
> >
> > Run your application and go through an authentication flow with a user who already has an MFA method enabled.
>
> > [tab] Optional enrollment
> >
> > ### Optional MFA enrollment
> >
> > If an Organization's MFA policy is `OPTIONAL`, members can still opt to secure their account with MFA. At a high level, the flow for this is very similar to required enrollment, but can occur anytime after the Member has logged in and has been granted a Session.
> >
> > The headless SDK will take care of including the `session_jwt` / `session_token` in the `authenticate()` calls, so the only additional piece you'd need to do is to pass in the `set_mfa_enrollment` flag:
> >
> > > [tab] SMS OTP
> > >
> > > ```jsx React icon=react theme={null}
> > > stytch.otps.sms.authenticate({
> > >   member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >   organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >   code: otpCode,
> > >   session_duration_minutes: 60,
> > >   set_mfa_enrollment: 'enroll'
> > > });
> > > ```
> > >
> > > ```javascript Vanilla JS icon=js theme={null}
> > > stytch.otps.sms.authenticate({
> > >   member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >   organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >   code: document.getElementById('otp-input').value,
> > >   session_duration_minutes: 60,
> > >   set_mfa_enrollment: 'enroll'
> > > });
> > > ```
> >
> > > [tab] TOTP
> > >
> > > ```jsx React icon=react theme={null}
> > > stytch.totp.authenticate({
> > >   member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >   organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >   code: totpCode,
> > >   session_duration_minutes: 60,
> > >   set_mfa_enrollment: 'enroll'
> > > });
> > > ```
> > >
> > > ```javascript Vanilla JS icon=js theme={null}
> > > stytch.totp.authenticate({
> > >   member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
> > >   organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
> > >   code: document.getElementById('totp-input').value,
> > >   session_duration_minutes: 60,
> > >   set_mfa_enrollment: 'enroll'
> > > });
> > > ```
> >
> > If the Member is enrolling in an additional form of MFA (e.g. has SMS MFA already, and is adding TOTP) you can also specify that the newly enrolled MFA method becomes the default through the `set_default_mfa` boolean.
> >
> > If you want to enroll the user in MFA for occasional step-up authentication on particularly sensitive actions, rather than MFA that is required on each login you can omit the `set_mfa_enrollment` field in the `authenticate()` call.

> [tab] Backend SDK
>
> > [tab] First-time enrollment
> >
> > ### Required MFA enrollment
> >
> > When an Organization's MFA policy is `REQUIRED_FOR_ALL` but the Member is not currently enrolled in MFA, you'll need to handle MFA enrollment after primary authentication.
> >
> > **1. Detect when MFA enrollment required**
> >
> > The following APIs will return a Member Session if the Member is not enrolled in MFA OR an `intermediate_session_token` and an `mfa_required` object that indicates MFA is required in order to be granted a Session for the Organization:
> >
> > * [Authenticate SSO](https://stytch.com/docs/api-reference/b2b/api/sso/shared/complete-sso-authenticate.md)
> > * [Authenticate OAuth](https://stytch.com/docs/api-reference/b2b/api/oauth/discovery/authenticate.md)
> > * [Authenticate Magic Link](https://stytch.com/docs/api-reference/b2b/api/email-magic-links/organization/authenticate-magic-link.md)
> > * [Authenticate Password](https://stytch.com/docs/api-reference/b2b/api/passwords/authenticate.md)
> > * [Exchange Session](https://stytch.com/docs/api-reference/b2b/api/sessions/exchange-session.md)
> > * [Password Reset by Email](https://stytch.com/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-email.md)
> > * [Password Reset by Existing Password](https://stytch.com/docs/api-reference/b2b/api/passwords/create-or-reset-options/password-reset-by-existing-password.md)
> >
> > If the Member is not yet enrolled in MFA, the response will look as follows:
> >
> > ```json theme={null}
> > {
> >     "intermediate_session_token": "oNJB3foIA79dn_uNVMNghG_MGkKSLHnR65NsKXv0gZzY",
> >     "mfa_required": {
> >         "member_options": null,
> >         "secondary_auth_initiated": null
> >     },
> >     "member_authenticated": false,
> >     "organization": {
> >         "mfa_methods": "REQUIRED_FOR_ALL",
> >         "allowed_mfa_methods": ["sms_otp", "totp"]
> >     }
> > }
> > ```
> >
> > Indicating that `member_authenticated: false` due to `mfa_required` -- but no `member_options` are present.
> >
> > For the primary authentication endpoint(s) you've already integrated add handling to detect when MFA enrollment is required by checking to see if the `organization.mfa_methods` is `ALL_ALLOWED` or `RESTRICTED`. If `RESTRICTED` use the `organization.allowed_mfa_methods` to surface only allowed MFA methods to the user.
> >
> > ```python Python icon=python theme={null}
> > @app.route("/authenticate", methods=["POST"])
> > def authenticate():
> >     # After primary authentication (e.g., magic link, password, OAuth)
> >     resp = stytch_client.magic_links.authenticate(
> >         magic_links_token=request.form.get("token")
> >     )
> >
> >     if resp.member_authenticated:
> >         # No MFA required, create session
> >         session["stytch_session_jwt"] = resp.session_jwt
> >         return redirect(url_for("dashboard"))
> >
> >     # MFA is required - store intermediate session token
> >     session["intermediate_session_token"] = resp.intermediate_session_token
> >
> >     # Check allowed MFA methods
> >     allowed_methods = resp.organization.allowed_mfa_methods
> >     if resp.organization.mfa_methods == "RESTRICTED":
> >         # Only show allowed methods to user
> >         return render_template("mfa_enrollment.html", allowed_methods=allowed_methods)
> >
> >     return render_template("mfa_enrollment.html", allowed_methods=["sms_otp", "totp"])
> > ```
> >
> > ```javascript Node.js icon=node theme={null}
> > app.post("/authenticate", async (req, res) => {
> >   // After primary authentication (e.g., magic link, password, OAuth)
> >   const resp = await stytchClient.magicLinks.authenticate({
> >     magic_links_token: req.body.token,
> >   });
> >
> >   if (resp.member_authenticated) {
> >     // No MFA required, create session
> >     req.session.stytch_session_jwt = resp.session_jwt;
> >     return res.redirect("/dashboard");
> >   }
> >
> >   // MFA is required - store intermediate session token
> >   req.session.intermediate_session_token = resp.intermediate_session_token;
> >
> >   // Check allowed MFA methods
> >   const allowedMethods = resp.organization.allowed_mfa_methods;
> >   if (resp.organization.mfa_methods === "RESTRICTED") {
> >     // Only show allowed methods to user
> >     return res.render("mfa_enrollment", { allowedMethods });
> >   }
> >
> >   return res.render("mfa_enrollment", { allowedMethods: ["sms_otp", "totp"] });
> > });
> > ```
> >
> > Your frontend should prompt the user to enroll in MFA via the allowed methods.
> >
> > For TOTP, no user input is required to start registration. For SMS, your frontend will need to collect the user's phone number in E.164 format (e.g., "+14155551234").
> >
> > **2. Start MFA enrollment**
> >
> > Add routes to handle starting the MFA enrollment process for SMS OTP or TOTP, depending on the users' selection.
> >
> > > [tab] SMS OTP
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/mfa/sms/send", methods=["POST"])
> > > def mfa_sms_send():
> > >     intermediate_session_token = session.get("intermediate_session_token")
> > >     if not intermediate_session_token:
> > >         return "No intermediate session", 400
> > >
> > >     phone_number = request.form.get("phone_number")
> > >
> > >     resp = stytch_client.otps.sms.send(
> > >         organization_id=session.get("organization_id"),
> > >         member_id=session.get("member_id"),
> > >         mfa_phone_number=phone_number,
> > >         intermediate_session_token=intermediate_session_token,
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error sending OTP", 500
> > >
> > >     return render_template("mfa_verify.html", mfa_type="sms")
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/mfa/sms/send", async (req, res) => {
> > >   const intermediateSessionToken = req.session.intermediate_session_token;
> > >   if (!intermediateSessionToken) {
> > >     return res.status(400).send("No intermediate session");
> > >   }
> > >
> > >   const phoneNumber = req.body.phone_number;
> > >
> > >   const resp = await stytchClient.otps.sms.send({
> > >     organization_id: req.session.organization_id,
> > >     member_id: req.session.member_id,
> > >     mfa_phone_number: phoneNumber,
> > >     intermediate_session_token: intermediateSessionToken,
> > >   });
> > >
> > >   return res.render("mfa_verify", { mfaType: "sms" });
> > > });
> > > ```
> >
> > > [tab] TOTP
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/mfa/totp/create", methods=["POST"])
> > > def mfa_totp_create():
> > >     intermediate_session_token = session.get("intermediate_session_token")
> > >     if not intermediate_session_token:
> > >         return "No intermediate session", 400
> > >
> > >     resp = stytch_client.totps.create(
> > >         organization_id=session.get("organization_id"),
> > >         member_id=session.get("member_id"),
> > >         intermediate_session_token=intermediate_session_token,
> > >         expiration_minutes=60,
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error creating TOTP", 500
> > >
> > >     # Return the QR code for the user to scan
> > >     return render_template(
> > >         "mfa_totp_setup.html",
> > >         qr_code=resp.qr_code,
> > >         secret=resp.secret,
> > >     )
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/mfa/totp/create", async (req, res) => {
> > >   const intermediateSessionToken = req.session.intermediate_session_token;
> > >   if (!intermediateSessionToken) {
> > >     return res.status(400).send("No intermediate session");
> > >   }
> > >
> > >   const resp = await stytchClient.totps.create({
> > >     organization_id: req.session.organization_id,
> > >     member_id: req.session.member_id,
> > >     intermediate_session_token: intermediateSessionToken,
> > >     expiration_minutes: 60,
> > >   });
> > >
> > >   // Return the QR code for the user to scan
> > >   return res.render("mfa_totp_setup", {
> > >     qrCode: resp.qr_code,
> > >     secret: resp.secret,
> > >   });
> > > });
> > > ```
> >
> > **3. Authenticate to complete enrollment**
> >
> > You'll want to add a route that allows the user to finish the enrollment process by authenticating with their chosen factor.
> >
> > > [tab] SMS OTP
> > >
> > > Your frontend should prompt the user for the 6-digit code they received via SMS and submit it along with:
> > >
> > > * `organization_id`: The Organization's ID
> > > * `member_id`: The Member's ID
> > > * `code`: The OTP code entered by the user
> > > * `intermediate_session_token`: The token from primary authentication
> > >
> > > When the user submits their OTP code, you'll call Stytch to authenticate the code. If successful, this will complete the Member's enrollment in MFA and grant them a Member Session.
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/mfa/sms/authenticate", methods=["POST"])
> > > def mfa_sms_authenticate():
> > >     intermediate_session_token = session.get("intermediate_session_token")
> > >     if not intermediate_session_token:
> > >         return "No intermediate session", 400
> > >
> > >     code = request.form.get("code")
> > >
> > >     resp = stytch_client.otps.sms.authenticate(
> > >         organization_id=session.get("organization_id"),
> > >         member_id=session.get("member_id"),
> > >         code=code,
> > >         intermediate_session_token=intermediate_session_token,
> > >         session_duration_minutes=60,
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error authenticating OTP", 500
> > >
> > >     # Clear intermediate session and set authenticated session
> > >     session.pop("intermediate_session_token", None)
> > >     session["stytch_session_jwt"] = resp.session_jwt
> > >
> > >     return redirect(url_for("dashboard"))
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/mfa/sms/authenticate", async (req, res) => {
> > >   const intermediateSessionToken = req.session.intermediate_session_token;
> > >   if (!intermediateSessionToken) {
> > >     return res.status(400).send("No intermediate session");
> > >   }
> > >
> > >   const code = req.body.code;
> > >
> > >   const resp = await stytchClient.otps.sms.authenticate({
> > >     organization_id: req.session.organization_id,
> > >     member_id: req.session.member_id,
> > >     code: code,
> > >     intermediate_session_token: intermediateSessionToken,
> > >     session_duration_minutes: 60,
> > >   });
> > >
> > >   // Clear intermediate session and set authenticated session
> > >   delete req.session.intermediate_session_token;
> > >   req.session.stytch_session_jwt = resp.session_jwt;
> > >
> > >   return res.redirect("/dashboard");
> > > });
> > > ```
> >
> > > [tab] TOTP
> > >
> > > For TOTP, you'll need to first surface the QR Code so the user can create a TOTP registration in their authenticator app. Once registered, your UI should prompt them to input the TOTP code from their authenticator app. Your frontend should submit:
> > >
> > > * `organization_id`: The Organization's ID
> > > * `member_id`: The Member's ID
> > > * `code`: The 6-digit TOTP code from their authenticator app
> > > * `intermediate_session_token`: The token from primary authentication
> > >
> > > When the user submits their TOTP code, you'll call Stytch to authenticate the code. If successful, this will complete the Member's enrollment in MFA and grant them a Member Session.
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/mfa/totp/authenticate", methods=["POST"])
> > > def mfa_totp_authenticate():
> > >     intermediate_session_token = session.get("intermediate_session_token")
> > >     if not intermediate_session_token:
> > >         return "No intermediate session", 400
> > >
> > >     code = request.form.get("code")
> > >
> > >     resp = stytch_client.totps.authenticate(
> > >         organization_id=session.get("organization_id"),
> > >         member_id=session.get("member_id"),
> > >         code=code,
> > >         intermediate_session_token=intermediate_session_token,
> > >         session_duration_minutes=60,
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error authenticating TOTP", 500
> > >
> > >     # Clear intermediate session and set authenticated session
> > >     session.pop("intermediate_session_token", None)
> > >     session["stytch_session_jwt"] = resp.session_jwt
> > >
> > >     return redirect(url_for("dashboard"))
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/mfa/totp/authenticate", async (req, res) => {
> > >   const intermediateSessionToken = req.session.intermediate_session_token;
> > >   if (!intermediateSessionToken) {
> > >     return res.status(400).send("No intermediate session");
> > >   }
> > >
> > >   const code = req.body.code;
> > >
> > >   const resp = await stytchClient.totps.authenticate({
> > >     organization_id: req.session.organization_id,
> > >     member_id: req.session.member_id,
> > >     code: code,
> > >     intermediate_session_token: intermediateSessionToken,
> > >     session_duration_minutes: 60,
> > >   });
> > >
> > >   // Clear intermediate session and set authenticated session
> > >   delete req.session.intermediate_session_token;
> > >   req.session.stytch_session_jwt = resp.session_jwt;
> > >
> > >   return res.redirect("/dashboard");
> > > });
> > > ```
> >
> > The member is now enrolled in MFA, and will be prompted to perform MFA through their selected method on subsequent authentication.
> >
> > **4. Test it out**
> >
> > Run your application and attempt to login to your Organization with the `REQUIRED_FOR_ALL` MFA policy to test out required enrollment in MFA.
>
> > [tab] Returning login
> >
> > ### Returning MFA authentication
> >
> > The flow for returning MFA authentication with a backend integration is quite similar to the last step of enrolling a Member in MFA for the first time.
> >
> > **1. Detect user's MFA options**
> >
> > When a Member is already enrolled in MFA, the response from the various `authenticate()` APIs discussed in the "Required MFA Enrollment" section will indicate this in the `mfa_required.member_options` object:
> >
> > ```json theme={null}
> > {
> >     "intermediate_session_token": "oNJB3foIA79dn_uNVMNghG_MGkKSLHnR65NsKXv0gZzY",
> >     "mfa_required": {
> >         "member_options": {
> >             "mfa_phone": "+14151112222",
> >             "totp_registration_id": "member-totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c"
> >         },
> >         "secondary_auth_initiated": "sms_otp"
> >     },
> >     "member_authenticated": false
> > }
> > ```
> >
> > If a Member's `default_mfa_method` is SMS OTP, Stytch will automatically trigger the SMS Send when the user performs primary authentication for that Organization and will indicate this in the `secondary_auth_initiated` field.
> >
> > Check the `member_options` and surface the appropriate input to the Member to complete MFA:
> >
> > ```python Python icon=python theme={null}
> > @app.route("/authenticate", methods=["POST"])
> > def authenticate():
> >     # After primary authentication
> >     resp = stytch_client.magic_links.authenticate(
> >         magic_links_token=request.form.get("token")
> >     )
> >
> >     if resp.member_authenticated:
> >         session["stytch_session_jwt"] = resp.session_jwt
> >         return redirect(url_for("dashboard"))
> >
> >     # MFA required - check member's enrolled methods
> >     session["intermediate_session_token"] = resp.intermediate_session_token
> >     member_options = resp.mfa_required.member_options
> >
> >     if member_options:
> >         # Member is already enrolled in MFA
> >         mfa_methods = []
> >         if member_options.mfa_phone:
> >             mfa_methods.append("sms_otp")
> >         if member_options.totp_registration_id:
> >             mfa_methods.append("totp")
> >
> >         # Check if SMS was auto-triggered
> >         sms_auto_sent = resp.mfa_required.secondary_auth_initiated == "sms_otp"
> >
> >         return render_template(
> >             "mfa_verify.html",
> >             mfa_methods=mfa_methods,
> >             sms_auto_sent=sms_auto_sent,
> >             masked_phone=member_options.mfa_phone,
> >         )
> >
> >     # Member needs to enroll in MFA
> >     return render_template("mfa_enrollment.html")
> > ```
> >
> > ```javascript Node.js icon=node theme={null}
> > app.post("/authenticate", async (req, res) => {
> >   // After primary authentication
> >   const resp = await stytchClient.magicLinks.authenticate({
> >     magic_links_token: req.body.token,
> >   });
> >
> >   if (resp.member_authenticated) {
> >     req.session.stytch_session_jwt = resp.session_jwt;
> >     return res.redirect("/dashboard");
> >   }
> >
> >   // MFA required - check member's enrolled methods
> >   req.session.intermediate_session_token = resp.intermediate_session_token;
> >   const memberOptions = resp.mfa_required.member_options;
> >
> >   if (memberOptions) {
> >     // Member is already enrolled in MFA
> >     const mfaMethods = [];
> >     if (memberOptions.mfa_phone) {
> >       mfaMethods.push("sms_otp");
> >     }
> >     if (memberOptions.totp_registration_id) {
> >       mfaMethods.push("totp");
> >     }
> >
> >     // Check if SMS was auto-triggered
> >     const smsAutoSent = resp.mfa_required.secondary_auth_initiated === "sms_otp";
> >
> >     return res.render("mfa_verify", {
> >       mfaMethods,
> >       smsAutoSent,
> >       maskedPhone: memberOptions.mfa_phone,
> >     });
> >   }
> >
> >   // Member needs to enroll in MFA
> >   return res.render("mfa_enrollment");
> > });
> > ```
> >
> > > [tab] SMS OTP
> > >
> > > Your frontend should prompt the user to input the OTP they received and submit it with:
> > >
> > > * `organization_id`: The Organization's ID
> > > * `member_id`: The Member's ID
> > > * `code`: The 6-digit OTP code
> > > * `intermediate_session_token`: The token from primary authentication
> >
> > > [tab] TOTP
> > >
> > > Your frontend should prompt the user to input their TOTP code from their authenticator app and submit it with:
> > >
> > > * `organization_id`: The Organization's ID
> > > * `member_id`: The Member's ID
> > > * `code`: The 6-digit TOTP code
> > > * `intermediate_session_token`: The token from primary authentication
> >
> > **2. Authenticate MFA**
> >
> > Similar to the last step of MFA enrollment, handle submission of the TOTP or OTP code in order to finish the MFA authentication and log the member in based on their default MFA method.
> >
> > > [tab] SMS OTP
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/mfa/sms/authenticate", methods=["POST"])
> > > def mfa_sms_authenticate():
> > >     intermediate_session_token = session.get("intermediate_session_token")
> > >     if not intermediate_session_token:
> > >         return "No intermediate session", 400
> > >
> > >     code = request.form.get("code")
> > >
> > >     resp = stytch_client.otps.sms.authenticate(
> > >         organization_id=session.get("organization_id"),
> > >         member_id=session.get("member_id"),
> > >         code=code,
> > >         intermediate_session_token=intermediate_session_token,
> > >         session_duration_minutes=60,
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error authenticating OTP", 500
> > >
> > >     session.pop("intermediate_session_token", None)
> > >     session["stytch_session_jwt"] = resp.session_jwt
> > >
> > >     return redirect(url_for("dashboard"))
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/mfa/sms/authenticate", async (req, res) => {
> > >   const intermediateSessionToken = req.session.intermediate_session_token;
> > >   if (!intermediateSessionToken) {
> > >     return res.status(400).send("No intermediate session");
> > >   }
> > >
> > >   const code = req.body.code;
> > >
> > >   const resp = await stytchClient.otps.sms.authenticate({
> > >     organization_id: req.session.organization_id,
> > >     member_id: req.session.member_id,
> > >     code: code,
> > >     intermediate_session_token: intermediateSessionToken,
> > >     session_duration_minutes: 60,
> > >   });
> > >
> > >   delete req.session.intermediate_session_token;
> > >   req.session.stytch_session_jwt = resp.session_jwt;
> > >
> > >   return res.redirect("/dashboard");
> > > });
> > > ```
> >
> > > [tab] TOTP
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/mfa/totp/authenticate", methods=["POST"])
> > > def mfa_totp_authenticate():
> > >     intermediate_session_token = session.get("intermediate_session_token")
> > >     if not intermediate_session_token:
> > >         return "No intermediate session", 400
> > >
> > >     code = request.form.get("code")
> > >
> > >     resp = stytch_client.totps.authenticate(
> > >         organization_id=session.get("organization_id"),
> > >         member_id=session.get("member_id"),
> > >         code=code,
> > >         intermediate_session_token=intermediate_session_token,
> > >         session_duration_minutes=60,
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error authenticating TOTP", 500
> > >
> > >     session.pop("intermediate_session_token", None)
> > >     session["stytch_session_jwt"] = resp.session_jwt
> > >
> > >     return redirect(url_for("dashboard"))
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/mfa/totp/authenticate", async (req, res) => {
> > >   const intermediateSessionToken = req.session.intermediate_session_token;
> > >   if (!intermediateSessionToken) {
> > >     return res.status(400).send("No intermediate session");
> > >   }
> > >
> > >   const code = req.body.code;
> > >
> > >   const resp = await stytchClient.totps.authenticate({
> > >     organization_id: req.session.organization_id,
> > >     member_id: req.session.member_id,
> > >     code: code,
> > >     intermediate_session_token: intermediateSessionToken,
> > >     session_duration_minutes: 60,
> > >   });
> > >
> > >   delete req.session.intermediate_session_token;
> > >   req.session.stytch_session_jwt = resp.session_jwt;
> > >
> > >   return res.redirect("/dashboard");
> > > });
> > > ```
> >
> > **3. Test it out**
> >
> > Run your application and go through an authentication flow with a user who already has an MFA method enabled.
>
> > [tab] Optional enrollment
> >
> > ### Optional MFA enrollment
> >
> > If an Organization's MFA policy is `OPTIONAL`, members can still opt to secure their account with MFA. At a high level, the flow for this is very similar to required enrollment, but can occur anytime after the Member has logged in and has been granted a Session.
> >
> > Add a route for optional enrollment that expects a `session_jwt` or `session_token` before calling the MFA Authentication endpoint that finalizes the enrollment. This can be used to add optional MFA to users or additional MFA methods to users who want to use both TOTP and SMS.
> >
> > > [tab] SMS OTP
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/optional-mfa-enrollment", methods=["POST"])
> > > def optional_mfa_enrollment():
> > >     jwt = session.get("stytch_session_jwt")
> > >     if not jwt:
> > >         return "No session", 400
> > >
> > >     resp = stytch_client.sessions.authenticate_jwt(session_jwt=jwt)
> > >     if resp.status_code != 200:
> > >         return "Invalid session", 401
> > >
> > >     organization_id = resp.member_session.organization_id
> > >     member_id = resp.member_session.member_id
> > >     code = request.form.get("code")
> > >
> > >     resp = stytch_client.otps.sms.authenticate(
> > >         session_jwt=jwt,
> > >         code=code,
> > >         organization_id=organization_id,
> > >         member_id=member_id,
> > >         set_mfa_enrollment="enroll",
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error authenticating MFA", 500
> > >
> > >     session["stytch_session_jwt"] = resp.session_jwt
> > >     return redirect(url_for("dashboard"))
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/optional-mfa-enrollment", async (req, res) => {
> > >   const jwt = req.session.stytch_session_jwt;
> > >   if (!jwt) {
> > >     return res.status(400).send("No session");
> > >   }
> > >
> > >   const authResp = await stytchClient.sessions.authenticateJwt({
> > >     session_jwt: jwt,
> > >   });
> > >
> > >   const organizationId = authResp.member_session.organization_id;
> > >   const memberId = authResp.member_session.member_id;
> > >   const code = req.body.code;
> > >
> > >   const resp = await stytchClient.otps.sms.authenticate({
> > >     session_jwt: jwt,
> > >     code: code,
> > >     organization_id: organizationId,
> > >     member_id: memberId,
> > >     set_mfa_enrollment: "enroll",
> > >   });
> > >
> > >   req.session.stytch_session_jwt = resp.session_jwt;
> > >   return res.redirect("/dashboard");
> > > });
> > > ```
> >
> > > [tab] TOTP
> > >
> > > ```python Python icon=python theme={null}
> > > @app.route("/optional-mfa-enrollment", methods=["POST"])
> > > def optional_mfa_enrollment():
> > >     jwt = session.get("stytch_session_jwt")
> > >     if not jwt:
> > >         return "No session", 400
> > >
> > >     resp = stytch_client.sessions.authenticate_jwt(session_jwt=jwt)
> > >     if resp.status_code != 200:
> > >         return "Invalid session", 401
> > >
> > >     organization_id = resp.member_session.organization_id
> > >     member_id = resp.member_session.member_id
> > >     code = request.form.get("code")
> > >
> > >     resp = stytch_client.totps.authenticate(
> > >         session_jwt=jwt,
> > >         code=code,
> > >         organization_id=organization_id,
> > >         member_id=member_id,
> > >         set_mfa_enrollment="enroll",
> > >     )
> > >
> > >     if resp.status_code != 200:
> > >         return "Error authenticating MFA", 500
> > >
> > >     session["stytch_session_jwt"] = resp.session_jwt
> > >     return redirect(url_for("dashboard"))
> > > ```
> > >
> > > ```javascript Node.js icon=node theme={null}
> > > app.post("/optional-mfa-enrollment", async (req, res) => {
> > >   const jwt = req.session.stytch_session_jwt;
> > >   if (!jwt) {
> > >     return res.status(400).send("No session");
> > >   }
> > >
> > >   const authResp = await stytchClient.sessions.authenticateJwt({
> > >     session_jwt: jwt,
> > >   });
> > >
> > >   const organizationId = authResp.member_session.organization_id;
> > >   const memberId = authResp.member_session.member_id;
> > >   const code = req.body.code;
> > >
> > >   const resp = await stytchClient.totps.authenticate({
> > >     session_jwt: jwt,
> > >     code: code,
> > >     organization_id: organizationId,
> > >     member_id: memberId,
> > >     set_mfa_enrollment: "enroll",
> > >   });
> > >
> > >   req.session.stytch_session_jwt = resp.session_jwt;
> > >   return res.redirect("/dashboard");
> > > });
> > > ```
> >
> > If the Member is enrolling in an additional form of MFA (e.g. has SMS MFA already, and is adding TOTP) you can also specify that the newly enrolled MFA method becomes the default through the `set_default_mfa` boolean.
> >
> > If you want to enroll the user in MFA for occasional step-up authentication on particularly sensitive actions, rather than MFA that is required on each login you can omit the `set_mfa_enrollment` field in the `authenticate()` call.
