One-time passcodes (OTP) for MFA

The React Native SDK provides methods to send and authenticate one-time passcodes (OTPs) via SMS that you can connect to your own UI. SMS OTPs cannot be used as a primary authentication mechanism. They can be used as a second factor for our enforced multi-factor authentication (MFA) suite, or they can be used as a step-up factor to be added to an existing session.

Methods

The SDK provides methods that can be used to send one-time passcodes (OTPs) via SMS and authenticate OTPs.

To call these methods, SMS Passcodes (OTP) must be enabled in the SDK Configuration page of the Stytch dashboard.

SMS Send

The SMS Send method wraps the send via SMS API endpoint. Call this method to send an SMS passcode to an existing Member.

If a Member has a phone number and is enrolled in MFA, then after a successful primary authentication event (e.g. email magic link authenticate or SSO authenticate is complete), an SMS OTP will automatically be sent to their phone number. In that case, this endpoint should only be used for subsequent authentication events, such as prompting a Member for an OTP again after a period of inactivity.

Cost to send SMS OTP

Before configuring SMS or WhatsApp OTPs, please review how Stytch bills the costs of international OTPs and understand how to protect your app against toll fraud.

Method parameters

organization_id* string

member_id* string

mfa_phone_number string

locale string

import React, { useCallback } from 'react';
import { useStytchB2BClient } from '@stytch/react/b2b';

export const Login = () => {
  const stytch = useStytchB2BClient();
  const sendPasscode = useCallback(() => {
    stytch.otps.sms.send({
      member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
      organization_id:'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
    });
  }, [stytch]);
  return <button onClick={sendPasscode}>Send passcode</button>;
};

RESPONSE

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141"
  }

SMS Authenticate

The SMS Authenticate method wraps the authenticate SMS API endpoint.

If there is a current Member Session, the SDK will call the endpoint with the session token. This will add the phone number factor to the existing Member Session. Otherwise, the SDK will use the intermediate session token. This will consume the intermediate session token and create a Member Session.

Intermediate session tokens are generated upon successful calls to primary authenticate methods in the case where MFA is required, such as email magic link authenticate, or upon successful calls to discovery authenticate methods, such as email magic link discovery authenticate.

If neither a Member Session nor an intermediate session token is present, this method will fail.

If this method succeeds, the Member will be logged in, granted an active session, and the session data will be persisted on device.

You can listen for successful login events anywhere in the codebase with the stytch.session.onChange() method or useStytchMemberSession hook.

Method parameters

organization_id* string

member_id* string

code* string

session_duration_minutes* int

set_mfa_enrollment string

import React, { 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 for="otp-input">Enter code</label>
      <input id="otp-input" autocomplete="one-time-code" inputtype="numeric" pattern="[0-9]*" onChange={handleChange} />
      <button onClick={authenticate} type="submit">
        Submit
      </button>
    </form>
  );
};

RESPONSE

{
  "status_code": 200,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
  "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
  "session_jwt": "example_jwt",
  "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
  "member_session": {...},
  "member": {...},
  "organization": {...}
}