TOTP-based sign-in protection
Protect accounts with authenticator applications.
Better Auth · Function
twoFactor
Better Auth’s twoFactor plugin adds TOTP and OTP second-factor authentication, along with backup codes and trusted-device support. Register it in the server auth configuration and set an issuer for TOTP enrollment.
How it works
The twoFactor plugin adds second-factor authentication to Better Auth. Users can use authenticator-generated TOTP codes or delivery-based OTP codes, with support for backup codes, activation management, and trusted devices.
Syntax
twoFactor(options?)Parameters
| Name | Type | Description |
|---|---|---|
options | TwoFactorOptions | Plugin configuration, including the issuer and optional OTP settings described by the documentation. |
Returns
A Better Auth two-factor plugin instance; enabling the feature returns method-specific data such as a TOTP URI and backup codes for TOTP, or the selected method for OTP.
Key points
- The plugin supports two second-factor modes: authenticator-generated TOTP and application-delivered OTP.
- Users can receive backup codes so they can recover access if the normal second-factor device is unavailable.
- The API includes operations for turning two-factor authentication on and off.
- Trusted-device support can reduce repeated verification on recognized devices.
- Configure an issuer name when registering the plugin; it identifies the application in TOTP enrollment data.
- For TOTP enrollment, the server creates a URI from the secret and issuer that can be rendered as a QR code.
Common mistakes
- Email/password users must supply their password when enabling two-factor authentication.
- The OTP method does not work until the server has a
sendOTPimplementation configured. - TOTP setup is not active until the user completes code verification.
Example: Register the two-factor plugin
import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [twoFactor({ issuer: "My App" })]
});Register the plugin on the server and provide the application name used as the issuer.
When to use it
Delivered OTP verification
Use email, SMS, or another application-managed delivery channel.
Backup-code recovery
Help users regain access without their usual authenticator.
Trusted-device sessions
Avoid prompting repeatedly on recognized hardware.
Interview questions
QWhat does the two-factor plugin provide?
twoFactor is a Better Auth plugin that adds a second verification step after primary sign-in. It supports TOTP from an authenticator app and OTP delivered through an application-configured channel.
Follow-up: How does the plugin distinguish the setup flows? TOTP returns a URI and backup codes after code verification, whereas OTP enables immediately and returns its method.
QHow do TOTP and OTP setup differ?
The default method is totp, which prepares authenticator-app enrollment and requires the user to verify a generated code. The alternative otp method enables email- or SMS-style verification immediately.
Follow-up: What server dependency does OTP have? The application must configure otpOptions.sendOTP so Better Auth can deliver the code.
QHow is second-factor verification integrated into the client?
After enabling two-factor authentication, the client can use the corresponding verification endpoint during sign-in. The client plugin also accepts a page destination for users who need to complete second-factor verification.
Follow-up: What related client behavior is supported? A successful trusted-device verification can prevent repeated second-factor prompts on that device.
Related
twoFactorClienttwoFactor.enabletwoFactor.disabletwoFactor.verifyTOTPauthClient.twoFactor.sendOtpauth.api.sendTwoFactorOTPsendOTP