Email OTP plugin installation and setup
The emailOTP plugin allows users to sign in, verify their email, or reset their password using a one-time password sent to their email address. Add the emailOTP plugin to the auth config and implement the sendVerificationOTP() method. The sendVerificationOTP() method receives an object with email, otp, and type properties, where type can be 'sign-in', 'email-verification', or 'forget-password'. Also add the emailOTPClient plugin to the client configuration.
Sign in with email OTP endpoint
POST /sign-in/email-otp. Parameters: email (string, required, default 'user@example.com'), otp (string, required, default '123456'), name (string, optional, default 'John Doe', only used when registering for first time), image (string, optional, default 'https://example.com/image.png', only used when registering for first time). If the user is not registered, they will be automatically registered. Configured additional fields are also accepted for new users.
Email OTP sign-in behavior with unverified email
When a sign-in OTP confirms a pre-existing account whose email was never verified, any existing password on that account is removed and its sessions are revoked. The user is signed in through the OTP and can set a new password through password reset. This keeps email ownership, proven by the OTP, as the source of truth for the account.
verifyEmail endpoint for email OTP
POST /email-otp/verify-email. Parameters: email (string, required, default 'user@example.com'), otp (string, required, default '123456').
requestPasswordReset endpoint for email OTP
POST /email-otp/request-password-reset. Parameters: email (string, required, default 'user@example.com'). The deprecated endpoint /forget-password/email-otp should not be used.
resetPassword endpoint for email OTP
POST /email-otp/reset-password. Parameters: email (string, required, default 'user@example.com'), otp (string, required, default '123456'), password (string, required, default 'new-secure-password').
Email OTP change email feature setup
To allow users to change their email with OTP, enable the changeEmail feature by setting changeEmail.enabled to true in the emailOTP plugin options. By default, when a user requests to change their email, an OTP is sent to the new email address and the email is only updated after the user verifies the new email.
changeEmail endpoint for email OTP
POST /email-otp/change-email (requires session). Parameters: newEmail (string, required, default 'user@example.com'), otp (string, required, default '123456').
Email OTP verify current email for email change
For added security, set changeEmail.verifyCurrentEmail to true in the plugin options to require users to confirm the change with an OTP sent to their current email before sending an OTP to the new email address. Before requesting the email change, send an OTP to the user's current email address using sendVerificationOtp with type 'email-verification'.
Override default email verification with email OTP
Pass overrideDefaultEmailVerification: true in the emailOTP plugin options to make the system use an email OTP instead of the default verification link whenever email verification is triggered. The user will verify their email using an OTP rather than clicking a link.
Email OTP plugin options: otpLength and expiresIn
otpLength: The length of the OTP, defaults to 6. expiresIn: The expiry time of the OTP in seconds, defaults to 300 seconds.
Email OTP plugin options: sendVerificationOnSignUp and disableSignUp
sendVerificationOnSignUp: A boolean value that determines whether to send the OTP when a user signs up, defaults to false. disableSignUp: A boolean value that determines whether to prevent automatic sign-up when the user is not registered, defaults to false.
Email OTP plugin options: generateOTP
generateOTP: A function that generates the OTP. Defaults to a random 6-digit number.
Email OTP plugin options: allowedAttempts
allowedAttempts: The maximum number of attempts allowed for verifying an OTP, defaults to 3. After exceeding this limit, the OTP becomes invalid and the user needs to request a new one. When maximum attempts are exceeded, the verifyOTP, signIn.emailOtp, verifyEmail, and resetPassword methods return an error with code TOO_MANY_ATTEMPTS.
Email OTP plugin options: resendStrategy
resendStrategy: Controls what happens when a user requests a new OTP while an existing one is still valid, defaults to 'rotate'. 'rotate': Always generates a new OTP (default behavior). 'reuse': Resends the same OTP and extends its expiry, preventing multiple valid codes from existing simultaneously. Only works when the OTP is recoverable (plain, encrypted, or custom encrypt/decrypt). Falls back to 'rotate' when the OTP is hashed. If allowed attempts have been exhausted, a fresh OTP is generated instead of reusing the exhausted one.
Email OTP plugin options: storeOTP
storeOTP: The method used to transform the OTP before it is stored, can be 'encrypted', 'hashed', or 'plain' text. Default is 'plain' text. This does not affect the OTP sent to the user, only the stored OTP value. Alternatively, pass a custom encryptor with encrypt and decrypt async functions, or a custom hasher with a hash async function.
Email OTP sendVerificationOTP implementation recommendation
It is recommended to not await the email sending in the sendVerificationOTP method to avoid timing attacks. On serverless platforms, use waitUntil or similar to ensure the email is sent.