Add multi-factor authentication (MFA) with SMS

Integrate Stytch one-time passcodes (OTP) as your multi-factor authentication solution.

Step 1: Build your UI for multi-factor authentication

Here’s an example of a multi-factor authentication flow. One screen accepts the user’s phone number and the other accepts their one-time passcode.

Step 2: Create or update user

The user you want to authenticate needs to be a Stytch user with an associated phone number. If they are, continue to Step 3. If the user already has a Stytch ID, send a UpdateUser request to add a phone number. If they don’t, send a CreateUser request to create a user with a phone number. We recommend saving the user and phone IDs in new columns of your users table or within a new table linking your users with their Stytch IDs.

curl --request POST \
  --url https://test.stytch.com/v1/users \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+12025550162"
  }'

Step 3: Send one-time passcode

Now that the phone number is associated with a Stytch user, send a SendOTPBySMS request. This will send a one-time passcode to the provided phone number. By default, the code will expire in 2 minutes. You can alter the expiration with the ExpirationMinutes request field.

curl --request POST \
  --url https://test.stytch.com/v1/otps/sms/send \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "phone_number": "+12025550162"
  }'

Step 4: Authenticate one-time passcode

The AuthenticateOTP endpoint will be used in conjunction with all SendOTPBySMS requests. The user should be prompted to enter the one-time passcode sent to them via SMS. After the user enters their code, send a AuthenticateOTP request with the code along with the phone ID used. If the response is a 200, the user is verified and can be logged in.

curl --request POST \
  --url https://test.stytch.com/v1/otps/authenticate \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "method_id": "phone-number-test-d5a3b680-e8a3-40c0-b815-ab79986666d0",
        "code": "${code}"
  }'