Email OTP Plugin#

Overview#

The emailOTP plugin provides OTP-based verification flows for email addresses, covering sign-in, email verification, password reset, and email change. It is registered at plugin ID "email-otp" 1 and exposes 11 endpoints backed by a shared verification table via internalAdapter.

Primary source files:

• packages/better-auth/src/plugins/email-otp/routes.ts — all endpoint handlers
• packages/better-auth/src/plugins/email-otp/utils.ts — identifier construction and helpers
• packages/better-auth/src/plugins/email-otp/otp-token.ts — OTP storage, verification, and reuse logic
• packages/better-auth/src/plugins/email-otp/types.ts — configuration type definitions
• packages/better-auth/src/plugins/email-otp/index.ts — plugin registration and rate-limit rules

Identifier Construction#

All stored OTPs are keyed by a compound identifier built by toOTPIdentifier:

{type}-otp-{email}

where type is one of "email-verification", "sign-in", "forget-password", or "change-email" 2.

change-email is the exception — compound two-email identifier. Instead of a single email, the identifier encodes both the current and new email as {type}-otp-{currentEmail}-{newEmail} 3. This ties the OTP to both addresses, so it cannot be replayed if either address changes.

All other types use the single-email form.

Endpoint Inventory#

5

Generic vs. type-specific endpoints#

/email-otp/send-verification-otp is the generic send endpoint: it accepts any type except "change-email" — passing change-email there is explicitly rejected with a BAD_REQUEST error and a hint to use the dedicated endpoint 6. The change-email flow has its own pair of endpoints (request-email-change / change-email) because it requires an active session, a two-address identifier, and optional current-email verification before sending to the new address.

Change-Email Flow#

The change-email flow is behind a feature flag (opts.changeEmail.enabled) 7 and requires a sensitiveSessionMiddleware on both endpoints 8 9.

Step 1 — POST /email-otp/request-email-change 10:

1. Optionally verifies the current email with an OTP first, if changeEmail.verifyCurrentEmail: true 11. This OTP uses the single-email identifier (email-verification-otp-{currentEmail}).
2. Stores a new OTP under the compound identifier change-email-otp-{currentEmail}-{newEmail} 3.
3. If the new email already belongs to an existing user, silently deletes the OTP and returns success: true (enumeration protection) 12.
4. Sends OTP to newEmail via sendVerificationOTP.

Step 2 — POST /email-otp/change-email 13:

1. Verifies OTP atomically against the compound identifier.
2. Confirms new email is still unoccupied 14.
3. Updates the user record (email = newEmail, emailVerified = true) and fires beforeEmailVerification / afterEmailVerification hooks 15.
4. Refreshes the session cookie with the new email 16.

OTP Storage & Security#

Stored value format: {storedOTP}:{attemptCount} — the attempt counter is embedded in-band 17. splitAtLastColon is used everywhere to parse this.

storeOTP option controls how the OTP is persisted 18:

All comparisons use constantTimeEqual to prevent timing attacks 20.

Atomic verification#

Critical endpoints (sign-in, verify-email, reset-password, change-email) call atomicVerifyOTP:

1. Pre-check: read record and throw OTP_EXPIRED before consuming (for better error messages).
2. Atomically consume via consumeVerificationValue — first concurrent caller wins; concurrent racers get null → INVALID_OTP.
3. If budget exhausted (attempts >= allowedAttempts, default 3): reject, do not recreate 21.
4. If wrong code: recreate record with incremented attempts and original expiry 22.

/email-otp/check-verification-otp uses a non-atomic path instead (read-then-update), so it is not suitable for production verification gating 23.

Resend Strategy#

Controlled by resendStrategy option 24:

• "rotate" (default): Always generates a fresh OTP, overwriting any existing one.
• "reuse": If a non-expired, non-exhausted OTP exists and is recoverable (not hashed), tryReuseOTP refreshes its expiry and returns the existing code. Falls back to rotate if the OTP is hashed or expired.

Configuration Reference#

Defined in types.ts:

Rate limits default to 3 requests per 60-second window across all plugin endpoints 25.