Authenticate with Email

Dashboard Configuration

Simply toggle on “Email” in the Log in & User Profile section of the developer console.

If users report delayed or missing OTP emails, see the Email OTP delivery troubleshooting guide.

Prerequisites

Before this: create and initialize a Dynamic client (see Creating a Dynamic Client, Initializing the Dynamic Client).

Usage

JavaScript

import {
  sendEmailOTP,
  verifyOTP,
  type OTPVerification
} from '@dynamic-labs-sdk/client';

// With the user's email, call sendEmailOTP to get the otpVerification
// Then, once the user inputs the OTP code, call verifyOTP to verify it and complete the authentication

let otpVerification: OTPVerification | null = null;

const signInWithEmail = async () => {
  // Replace '[e-mail]' with the user's email address
  otpVerification = await sendEmailOTP({ email: '[e-mail]' });
  // Store the otpVerification for later use with the verifyOTP function
};

const handleVerifyOTP = async () => {
  // Use the same otpVerification object that you got from the sendEmailOTP function
  // Replace '123456' with the OTP code entered by the user
  await verifyOTP({ otpVerification, verificationToken: '123456' });
};

React

useSendEmailOTP returns the otpVerification object as its data; pass it to useVerifyOTP to complete the flow.

import { useSendEmailOTP, useVerifyOTP } from '@dynamic-labs-sdk/react-hooks';
import { useState } from 'react';

function EmailSignIn() {
  const [email, setEmail] = useState('');
  const [verificationToken, setVerificationToken] = useState('');

  const { mutate: sendEmailOTP, data: otpVerification, reset } = useSendEmailOTP();
  const { mutate: verifyOTP, isPending: isVerifying } = useVerifyOTP();

  if (otpVerification) {
    return (
      <div>
        <input
          value={verificationToken}
          onChange={(e) => setVerificationToken(e.target.value)}
          placeholder="Enter OTP"
        />
        <button onClick={() => verifyOTP({ otpVerification, verificationToken })} disabled={isVerifying}>
          Verify
        </button>
        <button onClick={() => reset()}>Back</button>
      </div>
    );
  }

  return (
    <div>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email address"
      />
      <button onClick={() => sendEmailOTP({ email })}>Send OTP</button>
    </div>
  );
}

If a user is already signed in, verifyOTP links the email to that user instead of signing in. If the project requires step-up authentication to link an email, verification fails with HTTP 403 and “Elevated access token required”. If you intend to sign a user in, call logout() before sendEmailOTP (or useLogout in React).

import { logout, sendEmailOTP } from '@dynamic-labs-sdk/client';

await logout();
const otpVerification = await sendEmailOTP({ email: '[e-mail]' });

In React, sign the user out with useLogout before sending the code:

import { useLogout, useSendEmailOTP } from '@dynamic-labs-sdk/react-hooks';

const { mutateAsync: logout } = useLogout();
const { mutateAsync: sendEmailOTP } = useSendEmailOTP();

const signInWithEmail = async (email: string) => {
  await logout();
  return sendEmailOTP({ email });
};

Rate Limits

Email verification is subject to the following rate limits:

• 3 attempts per 10 minutes per email address

This is in place to protect deliverability of emails and to prevent abuse.

If users report delayed or missing OTP emails, see the Email OTP delivery troubleshooting guide.