Remembered device - Stytch Docs

You can see a hosted demo of this flow at our demo application here. On the stytchdemo.com homepage, it is the “Remembered Device” recipe card. The relevant code is in GitHub here.

In this guide we’ll walk through how to use Stytch’s Device Fingerprinting (DFP) product to implement a remembered device flow. Remembered device flows are a form of adaptive MFA, or triggering MFA only on unreco gnized logins. For this guide, we’ll use the Visitor ID as the known device identifier. Visitor ID is a cookie-based identifier, and is a good choice for allowlists because good actors don’t often intentionally clear their cookies, though it can happen naturally - for example, if they use a different browser. Other good examples for trigger points are login attempts from a new IP address or a new country. We’ll be using a Stytch Consumer project in a NextJS application for the purposes of this guide, but the same basic steps apply to any auth implementation. You will:

Generate device fingerprints

Generate device fingerprints and signals from the frontend and submit them as part of the authentication request.

Evaluate device recognition

Evaluate whether this is a recognized device using either the Stytch Device Fingerprinting Lookup response or the user_device authentication response field, depending on which approach you choose in step 2, and Stytch User metadata.

Conditionally show data

Conditionally show super-secret data within the application if either:

The login request is from a known device, or
The request is from a new device and the user completes Step-up MFA.

Store context and update devices

Store this context in Session custom claims via a claim called authorized_for_secret_data for future reference throughout your application, and update the Known Devices list.

Before you start

In order to complete this guide, you’ll need:

A Stytch project (either Consumer or B2B).
- If you don’t have one already, in the Dashboard, click on your existing project name in the top left corner of the Dashboard. Click Create Project, and then select B2B Authentication or Consumer Authentication.
Access to Device Fingerprinting. If you don’t have access, you can request a trial.
A basic authentication flow on which to add adaptive MFA.
- If you don’t have one set up already, you can use one of our example apps. The snippets in this guide will follow a recipe from our Next.js demo application (code here - look for “remembered device” files).
- This guide uses Stytch for authentication, but any backend authentication implementation can work.
- If you are using Stytch for authentication, this guide assumes you’re using a Consumer project. The same steps would apply to B2B projects as well if you don’t want to use Stytch’s built-in B2B MFA offerings.

Step-by-step walkthrough

Generating signals

The first step of this guide is step 1 and 2 of the Getting Started guide.Add the Stytch telemetry script to your login page:

<head>
    <script src="https://elements.stytch.com/telemetry.js"></script>
</head>

Add a method or event handler to call the async function GetTelemetryID(), which gathers signals from the device and resolves to a telemetry_id.

const authenticateWithTelemetry = async () => {

// Get telemetry_id from the telemetry script
let telemetryId: string | undefined;

try {
  const publicToken = process.env.NEXT_PUBLIC_STYTCH_PUBLIC_TOKEN;
  telemetryId = await (window as any).GetTelemetryID({ publicToken });
} catch (telemetryError) {
  console.warn('Could not get telemetry ID:', telemetryError);
}

When you call your backend authenticate endpoint, send the telemetry_id along as well.In the snippet below from the example app flow, we’re using Email Magic Links as our authentication method, so the telemetry_id is generated and sent along in the request to authenticate the Magic Link token.

// Call our authenticate API
const response = await fetch('/api/authenticate_eml_remembered_device', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    ...(telemetryId && { 'X-Telemetry-ID': telemetryId }),
  },
  body: JSON.stringify({ token }),
});

Authentication and remembered device evaluation

Stytch integrated approach
Standalone DFP

The Stytch integrated approach assumes you are using Stytch for authentication and Device Fingerprinting and relies on specific Stytch features. If you are not using Stytch for auth, switch to the Standalone DFP tab.Your backend endpoint will:

Authenticate the Email Magic Link token.
Get the Visitor ID from the user_device response.
Compare this against the known devices list to determine whether this is a known device or not.
Store the remembered device context in session.custom_claims for reference downstream.

// First, authenticate the magic link token and include the telemetry_id
let authenticateResponse = await stytchClient.magicLinks.authenticate({
  token: token,
  session_duration_minutes: 10080,
  telemetry_id: telemetryId,
});

You can grab the visitor_id from the user_device response field. Determine whether MFA is required based on whether the request is from a known device:

If known:
- Set authorized_for_secret_data: true in the Session claims
- Return super secret data already, or optionally return it elsewhere in your application, gated on session.custom_claims.authorized_for_secret_data: true
If not known:
- Store the pending Visitor ID in session custom claims for reference later on (to add to the known devices list in the case of a successful MFA flow)
- Set authorized_for_secret_data: false in the Session claims
- Let the frontend know that MFA is required

Note that the user_device in the response could be null if the fingerprint lookup failed for any reason, such as an invalid telemetry_id. If the user_device is null, you should fail closed and always require MFA for security reasons.

// Function to determine if a device is known
function isKnownDevice(visitorID: string, knownDevices: string[]) {
    return knownDevices.includes(visitorID);
}

// Get the list of already known devices and the visitor ID of this request
const knownDevices = authenticateResponse.user.trusted_metadata?.known_devices || [];
// Fail closed: if the `visitor_id` is not present in the response, require MFA
const visitorID = authenticateResponse.user_device?.visitor_id ?? '';

// Check if the Visitor ID is in the known devices list
const knownDevice = isKnownDevice(visitorID, knownDevices) && visitorID !== '';

// Set the session cookie in the response
cookies.set('api_sms_remembered_device_session', authenticateResponse.session_token, {
  httpOnly: true,
  maxAge: 1000 * 60 * 30,
});

// Update the session
if (knownDevice) {
  // Update session with custom claims to mark this session as authorized
  await stytchClient.sessions.authenticate({
    session_token: authenticateResponse.session_token,
    session_custom_claims: {
      authorized_for_secret_data: true,
      authorized_device: visitorID,
    },
  });
} else {
  // Store pending visitorID in session custom claims for later retrieval during OTP auth
  await stytchClient.sessions.authenticate({
    session_token: authenticateResponse.session_token,
    session_custom_claims: {
      authorized_for_secret_data: false,
      pending_device: visitorID,
    },
  });
}

Your backend endpoint will:

Authenticate the Email Magic Link token.
Make the DFP /lookup call to determine the Visitor ID.
Compare this against the known devices list to determine whether this is a known device or not.
Store the remembered device context in session.custom_claims for reference downstream.

// First, authenticate the magic link token
const authenticateResponse = await stytchClient.magicLinks.authenticate({
  token: token,
  session_duration_minutes: 10080,
});

// Get the list of already known devices:

const knownDevices = authenticateResponse.user.trusted_metadata?.known_devices || [];

Perform the /lookup call to check the Visitor ID for this login request:

// Fail closed: require MFA if no telemetry ID provided
if (!telemetryId) {
  console.log('No telemetry ID provided, requiring MFA (fail closed)');
  requiresMfa = true;
} else {
  try {
    // Lookup the telemetry ID response to get the Visitor ID
    const fingerprintResponse = await stytchClient.fraud.fingerprint.lookup({
      telemetry_id: telemetryId,
    });

  // Logic for decisioning is in the following snippets

  } catch (err) {
    console.error('Error checking remembered device:', telemetryError);
    // Fail closed: if telemetry lookup fails, require MFA for security
    requiresMfa = true;
  }
}

In the block where you successfully get a lookup response, determine whether MFA is required based on whether the request is from a known device:

If the device is known:
- Set authorized_for_secret_data: true in the Session claims
- Return super secret data in the response
- Or, optionally return super secret data elsewhere in your application, gated on session.custom_claims.authorized_for_secret_data: true
Otherwise, the device is not known:
- Store the pending Visitor ID in session custom claims for reference later on (to add to the known devices list in the case of a successful MFA flow)
- Set authorized_for_secret_data: false in the Session claims
- Let the frontend know that MFA is required

// Function to determine if a device is known
function isKnownDevice(visitorID: string, knownDevices: string[]) {
  return knownDevices.includes(visitorID);
}

// Default to closed
let requiresMfa = true;

    ... // Inside the try/catch from above:

    // Check if the Visitor ID is in the known devices list
    if (isKnownDevice(visitorID, knownDevices) && visitorID !== '') {
      console.log('Visitor ID is known, no MFA required');
      requiresMfa = false;
      // Update session with custom claims to mark this session as authorized
      await stytchClient.sessions.authenticate({
        session_token: authenticateResponse.session_token,
        session_custom_claims: {
          authorized_for_secret_data: true,
          authorized_device: visitorID,
        },
      });
    } else {
      console.log('Visitor ID is not known, MFA required');
      requiresMfa = true;
      // Store pending visitorID in session custom claims for later retrieval during OTP auth
      await stytchClient.sessions.authenticate({
        session_token: authenticateResponse.session_token,
        session_custom_claims: {
          authorized_for_secret_data: false,
          pending_device: visitorID,
        },
      });
    }

Finally, return a response to your frontend with the Session. In this example, we go ahead and include the super secret data in the response if MFA isn’t required.

return res.status(200).json({
  session_token: authenticateResponse.session_token,
  visitorID: visitorID,
  user_id: authenticateResponse.user_id,
  super_secret_data: knownDevice ? SUPER_SECRET_DATA.REMEMBERED_DEVICE : undefined,
});

Conditional access and MFA enforcement

Trusted Device → Grant AccessUntrusted Device → Prompt MFANow your application enters the Conditional Access and MFA Enforcement step: Trusted devices receive access to the protected data; unrecognized devices must complete MFA before access is granted.Below are two different approaches - the first uses a dedicated backend endpoint, the other uses React’s getServerSideProps:

Backend
React

In our integrated example application recipe, we implement that logic in a backend endpoint called /api/known_devices_integrated.

export async function handler(req: NextApiRequest, res: NextApiResponse<ErrorData | SuccessData>) {
  if (req.method === 'POST') {
    // Lookup the session to get the user id
    const cookies = new Cookies(req, res);
    const storedSession = cookies.get('api_sms_remembered_device_session');
    if (!storedSession) {
      return res.status(400).json({ errorString: 'No session provided' });
    }
    const stytchClient = loadStytch();
    const { session, user } = await stytchClient.sessions.authenticate({
      session_token: storedSession,
    });
    const hasRegisteredPhone = user.phone_numbers.length > 0;

    const phoneNumber = user.phone_numbers[0]?.phone_number ?? '';

    // Server-side authorization check based on session authentication factors and custom claims
    const hasEmailFactor = session.authentication_factors.find((i: any) => i.delivery_method === 'email');
    const hasSmsFactor = session.authentication_factors.find((i: any) => i.delivery_method === 'sms');
    const visitorID = session.custom_claims?.authorized_device || session.custom_claims?.pending_device || 'no visitor ID';

    let superSecretData = null;
    let requiresMfa = true; // Default to requiring MFA unless session proves otherwise
    const isRememberedDevice = session.custom_claims?.authorized_for_secret_data;

    if (hasEmailFactor && hasSmsFactor) {
      // User has completed full MFA - authorized for super secret data
      superSecretData = SUPER_SECRET_DATA.FULL_MFA;
      requiresMfa = false;
    } else if (isRememberedDevice) {
      // User is in a remembered device location (authorized during EML auth via session claims)
      superSecretData = SUPER_SECRET_DATA.REMEMBERED_DEVICE;
      requiresMfa = false;
    } else {
      // User needs MFA - either no email factor or not in trusted location
      requiresMfa = true;
    }

    // Get the known devices for the user
    const deviceList = user.trusted_metadata?.known_devices || [];

    // Return success
    return res.status(200).json({
      deviceList,
      user,
      session,
      hasRegisteredPhone,
      phoneNumber,
      superSecretData,
      isRememberedDevice,
      requiresMfa,
      visitorID,
    });
  } else {
    return res.status(405).end();
  }
}

In our standalone example application recipe, we implement that logic in getServerSideProps. Notably, all of the variables used in the logic here cannot be changed or accessed by a user:

export const getServerSideProps: GetServerSideProps = async (context) => {
  const cookies = new Cookies(context.req, context.res);
  const storedSession = cookies.get('api_sms_remembered_device_session');

  ...

    // Get the session data
    const { session } = await stytchClient.sessions.authenticate({ session_token: storedSession });

    let superSecretData = null;
    let isRememberedDevice = false;
    let requiresMfa = true; // Default to requiring MFA unless session proves otherwise
    let visitorID = '';

    // Server-side authorization check based on session authentication factors
    const hasEmailFactor = session.authentication_factors.find((i: any) => i.delivery_method === 'email');
    const hasSmsFactor = session.authentication_factors.find((i: any) => i.delivery_method === 'sms');

    if (hasEmailFactor && hasSmsFactor) {
      // User has completed full MFA - authorized for super secret data
      superSecretData = SUPER_SECRET_DATA.FULL_MFA;
      requiresMfa = false;
    } else if (hasEmailFactor && session.custom_claims?.authorized_for_secret_data) {
      // User is in a remembered device location (authorized during EML auth via session claims)
      superSecretData = SUPER_SECRET_DATA.REMEMBERED_DEVICE;
      isRememberedDevice = true;
      requiresMfa = false;
      visitorID = session.custom_claims.authorized_device as string || '';
    } else {
      // User needs MFA - either no email factor or not in trusted location
      requiresMfa = true;
      visitorID = session.custom_claims?.pending_device as string || '';
    }

   return {
      props: {
        user: JSON.parse(JSON.stringify(user)),
        session: JSON.parse(JSON.stringify(session)),
        ...
        superSecretData,
        isRememberedDevice,
        requiresMfa,
        visitorID,
      },
}

Use this known device data to determine frontend behavior; for example, the React component in our example app looks like:

// Fetch the known devices data from the endpoint above:
  useEffect(() => {
    const fetchKnownDevices = async () => {
      const resp = await fetch('/api/known_devices_integrated', { method: 'POST' });
      const data = await resp.json();
      if (data.errorString) {
        setError(data.errorString);
      } else {
        setDeviceResponse(data as SuccessData);
      }
    };
    fetchKnownDevices();
  }, []);

...

<div style={styles.secretBox}>
  <h3>Super secret area</h3>
  {deviceResponse.superSecretData ? (
    <div>
      <p>{deviceResponse.superSecretData}</p>
      {deviceResponse.isRememberedDevice && (
        <p style={styles.rememberedDeviceNote}>
          🎉 <strong>Device remembered!</strong>
        </p>
      )}
    </div>
  ) : (
    <>
      <Image alt="Lock" src={lock} width={100} />
      <p>
        {deviceResponse.requiresMfa
          ? `Additional authentication required. This appears to be a new device (${deviceResponse.visitorID || 'unknown device'}). Please complete SMS verification to continue.`
          : 'Super secret profile information is secured by two factor authentication. To unlock this area complete the SMS OTP flow.'
        }
      </p>
      {deviceResponse.hasRegisteredPhone && deviceResponse.phoneNumber ? (
        <SMSOTPButton phoneNumber={deviceResponse.phoneNumber} />
      ) : (
        <SMSRegister />
      )}
    </>
  )}
</div>

Update known devices list

If a user logs in from a new Visitor ID and successfully completes MFA, add that new visitor ID to the known devices list so they can skip MFA in subsequent logins.This should be done on your backend and require a Session with both factors (primary and MFA):

export async function handler(req: NextApiRequest, res: NextApiResponse<ErrorData | SuccessData>) {
  const stytchClient = loadStytch();

  // Get session from cookie
  const cookies = new Cookies(req, res);
  const storedSession = cookies.get('api_sms_remembered_device_session');

  // Authenticate the session to get user ID and verify factors
  const { session } = await stytchClient.sessions.authenticate({ session_token: storedSession });

  // Verify that the session has both EML and SMS factors (proving MFA completion)
  const hasEmailFactor = session.authentication_factors.some(f => f.delivery_method === 'email');
  const hasSmsFactor = session.authentication_factors.some(f => f.delivery_method === 'sms');

  if (!hasEmailFactor || !hasSmsFactor) {
    return res.status(403).json({ errorString: 'MFA not completed. Both email and SMS factors required.' });
  }

  // Get the pending device from session custom claims that was stored during EML authentication
  const pendingDevice = session.custom_claims?.pending_device;

  // Get user to access existing trusted metadata
  const user = await stytchClient.users.get({ user_id: session.user_id });

  // Get existing known devices or initialize empty array
  const existingKnownDevices = user.trusted_metadata?.known_devices || [];

  // Add new device if it's not already in the list
  if (!existingKnownDevices.includes(pendingDevice)) {
    const updatedKnownDevices = [...existingKnownDevices, pendingDevice];

    // Update the user's trusted metadata and clean up pending device
    await stytchClient.users.update({
      user_id: session.user_id,
      trusted_metadata: {
        ...user.trusted_metadata,
        known_devices: updatedKnownDevices,
        pending_device: undefined, // Remove the pending device
      },
    });

...
}

What’s next?

Want to try Stytch Device Fingerprinting?

Find out why Stytch’s device intelligence is trusted by Calendly, Replit, and many more.

​Before you start

​Step-by-step walkthrough

​What’s next?

Want to try Stytch Device Fingerprinting?

Before you start

Step-by-step walkthrough

What’s next?