Email OTP plugin purpose
The Email OTP plugin allows users to sign in, verify their email, or reset their password using a one-time password (OTP) sent to their email address.
email otp
28 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Email OTP plugin installation steps
To install the Email OTP plugin: (1) Import emailOTP from 'better-auth/plugins' and add it to the plugins array in betterAuth config. (2) Implement the sendVerificationOTP() method with parameters email, otp, and type ('sign-in', 'email-verification', or 'forget-password'). (3) Add emailOTPClient to the client plugins array by importing from 'better-auth/client/plugins'.
Email OTP sign-in endpoint and parameters
Endpoint: POST /sign-in/email-otp. Parameters: email (string, required, example 'user@example.com'), otp (string, required, example '123456'), name (string, optional, example 'John Doe', used only when registering first time), image (string, optional, example 'https://example.com/image.png', used only when registering first time).
Email OTP automatic sign-up behavior
If the user is not registered when signing in with email OTP, they are automatically registered. Configured additional fields are also accepted for new users. To prevent automatic sign-up, pass disableSignUp as true in the plugin options.
Email OTP sign-in account takeover security
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.
Email OTP verify email endpoint and parameters
Endpoint: POST /email-otp/verify-email. Parameters: email (string, required, example 'user@example.com'), otp (string, required, example '123456').
Email OTP reset password endpoint and parameters
Endpoint: POST /email-otp/reset-password. Parameters: email (string, required, example 'user@example.com'), otp (string, required, example '123456'), password (string, required, example 'new-secure-password').
Email OTP change email feature configuration
To enable email change with OTP, set 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 verification.
Email OTP change email endpoint and parameters
Endpoint: POST /email-otp/change-email (requires session). Parameters: newEmail (string, required, example 'user@example.com'), otp (string, required, example '123456').
Email OTP verify current email before change configuration
Set changeEmail.verifyCurrentEmail to true in plugin options to require users to confirm the email change with an OTP sent to their current email before sending an OTP to the new email address.
Email OTP override default email verification
Set overrideDefaultEmailVerification to true in emailOTP plugin options to use email OTP instead of the default verification link whenever email verification is triggered. Users will verify their email using an OTP rather than clicking a link.
Email OTP sendVerificationOTP option
The sendVerificationOTP function is a required option that sends the OTP to the user's email. It receives an object with properties: email (user's email address), otp (the OTP to send), type (the type of OTP: 'sign-in', 'email-verification', or 'forget-password'). It is recommended to not await the email sending to avoid timing attacks; on serverless platforms use waitUntil or similar to ensure the email is sent.
Email OTP otpLength option
The otpLength option controls the length of the OTP. Defaults to 6.
Email OTP expiresIn option
The expiresIn option sets the expiry time of the OTP in seconds. Defaults to 300 seconds.
Email OTP sendVerificationOnSignUp option
The sendVerificationOnSignUp option is a boolean that determines whether to send the OTP when a user signs up. Defaults to false.
Email OTP disableSignUp option
The disableSignUp option is a boolean that determines whether to prevent automatic sign-up when the user is not registered. Defaults to false.
Email OTP generateOTP option
The generateOTP option is a function that generates the OTP. Defaults to a random 6-digit number.
Email OTP allowedAttempts option
The allowedAttempts option sets 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 resendStrategy option
The resendStrategy option controls what happens when a user requests a new OTP while an existing one is still valid. Defaults to 'rotate'. Options: 'rotate' (always generates a new OTP, default), 'reuse' (resends the same OTP and extends its expiry, prevents multiple valid codes from existing simultaneously, only works when OTP is recoverable - plain, encrypted, or custom encrypt/decrypt, falls back to rotate when OTP is hashed, if allowed attempts exhausted a fresh OTP is generated instead of reusing the exhausted one).
Email OTP storeOTP option
The storeOTP option specifies the method to transform the OTP before storage by Better Auth's verification layer. Values: 'encrypted', 'hashed', or 'plain' text. Default is 'plain' text. This only affects the stored OTP value, not the OTP sent to the user. The storage backend itself is controlled by the global verification config; if secondaryStorage is configured, verification records can live there instead of the database. Alternatively, pass a custom encryptor with encrypt and decrypt async functions, or a custom hasher with a hash async function.
Email OTP plugin configuration example with otpLength and expiresIn
Example code showing email OTP plugin configuration: import { betterAuth } from "better-auth" import { emailOTP } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ emailOTP({ otpLength: 8, expiresIn: 600 }) ] })
Email OTP plugin configuration example with allowedAttempts
Example code showing email OTP plugin configuration with allowedAttempts: import { betterAuth } from "better-auth" import { emailOTP } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ emailOTP({ allowedAttempts: 5, // Allow 5 attempts before invalidating the OTP expiresIn: 300 }) ] })
Email OTP plugin configuration example with resendStrategy
Example code showing email OTP plugin configuration with resendStrategy: import { betterAuth } from "better-auth" import { emailOTP } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ emailOTP({ resendStrategy: "reuse", // [!code highlight] async sendVerificationOTP({ email, otp, type }) { // send the OTP }, }) ] })
Email OTP plugin configuration example with changeEmail verifyCurrentEmail
Example code showing email OTP plugin configuration with changeEmail verifyCurrentEmail: import { betterAuth } from "better-auth"; export const auth = betterAuth({ plugins: [ emailOTP({ changeEmail: { enabled: true, verifyCurrentEmail: true, } }) ] })
Email OTP plugin configuration example with overrideDefaultEmailVerification
Example code showing email OTP plugin configuration with overrideDefaultEmailVerification: import { betterAuth } from "better-auth"; import { emailOTP } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ emailOTP({ overrideDefaultEmailVerification: true, async sendVerificationOTP({ email, otp, type }) { // Implement the sendVerificationOTP method to send the OTP to the user's email address }, }), ], });
Email OTP plugin basic installation example
Example code for basic email OTP plugin installation: import { betterAuth } from "better-auth" import { emailOTP } from "better-auth/plugins" export const auth = betterAuth({ plugins: [ emailOTP({ async sendVerificationOTP({ email, otp, type }) { if (type === "sign-in") { // Send the OTP for sign in } else if (type === "email-verification") { // Send the OTP for email verification } else { // Send the OTP for password reset } }, }) ] })
Email OTP client plugin installation
Example code for email OTP client plugin installation: import { createAuthClient } from "better-auth/client" import { emailOTPClient } from "better-auth/client/plugins" export const authClient = createAuthClient({ plugins: [ emailOTPClient() ] })
Email OTP storeOTP custom hasher example
Example code for Email OTP custom hasher: emailOTP({ storeOTP: { hash: async (otp) => { return myCustomHasher(otp); }, } })