B2B Saas Authentication

/

SDKs

/

JavaScript SDK reference

/

Time-based One-time Passcodes (TOTPs) for MFA

Time-based one-time passcodes (TOTP) for MFA

The JavaScript SDK provides methods to create and authenticate time-based one-time passcodes (TOTPs) that you can connect to your own UI. TOTPs 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 create and authenticate time-based one-time passcodes (TOTPs) via authenticator apps.

To call these methods, TOTP must be enabled in the SDK Configuration page of the Stytch dashboard.

TOTP Create

The TOTP Create method wraps the create endpoint. Call this method to create a TOTP registration on an existing Member.


Method parameters


organization_id*string

member_id*string

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

export const CreateTOTP = () => {
  const stytchClient = useStytchB2BClient();

  const trigger = useCallback(() => {
    stytchClient.totp.create({
      expiration_minutes: 60,
      member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
      organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
    });
  }, [stytchClient]);

  return <button onClick={trigger}>Create TOTP</button>;
};

RESPONSE

200
{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "secret": "BTGNX5RKJRMQWQFRQKTG34JCF6XDRHZS",
    "totp_id": "totp-test-41920359-8bbb-4fe8-8fa3-aaa83f35f02c",
    "qr_code": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAG8ElEQVR...8EAAD//7dQP/5Y00bRAAAAAElFTkSuQmCC",
    "recovery_codes": [
    "ckss-2skx-ebow",
    "spbc-424h-usy0",
    "hi08-n5tk-lns5",
    "1n6i-l5na-8axe",
    "aduj-eufq-w6yy",
    "i4l3-dxyt-urmx",
    "ayyi-utb0-gj0s",
    "lz0m-02bi-psbx",
    "l2qm-zrk1-8ujs",
    "c2qd-k7m4-ifmc"
  ]
    "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
    "member": {...},
  }

TOTP Authenticate

The TOTP Authenticate method wraps the authenticate TOTP API endpoint.

If there is a current Member Session, the SDK will call the endpoint with the session token. This will add the totp 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 cookies will be minted and stored in the browser.

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


Method parameters


organization_id*string

member_id*string

code*string

session_duration_minutes*int

set_mfa_enrollmentstring

set_default_mfaboolean
import React, { 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({
        member_id: 'member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f',
        organization_id: 'organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931',
        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>
  );
};

RESPONSE

200
{
  "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": {...}
}