Phone-based registration and login
Users authenticate without relying on email addresses.
Better Auth · Const
phoneNumber
phoneNumber is Better Auth’s server plugin for phone-number authentication. It supports OTP verification and can enable phone-based sign-up and password sign-in flows.
How it works
phoneNumber registers phone-number authentication for Better Auth. It supplies OTP-based verification and can support sign-up or password sign-in flows; the server callback is responsible for delivering each generated code, typically through SMS.
Syntax
phoneNumber(options)Parameters
| Name | Type | Description |
|---|---|---|
options | PhoneNumberOptions | Configuration object for the phone-number plugin, including the OTP delivery callback and optional sign-up behavior. |
Returns
A Better Auth phone-number plugin configuration object.
Key points
- Use the plugin when authentication must support phone-number-based registration or login.
- Phone ownership is checked with one-time passwords.
- Configure OTP delivery with a callback that receives the destination number and generated code.
- Start verification by calling the documented endpoint that sends a code.
- The verification step requires the user to submit the received OTP.
Common mistakes
- After adding the plugin, update the database schema before using phone-number authentication.
- Phone-number sign-up with
signUpOnVerificationalso needs a function that creates a temporary email.
Example: Configure phone number authentication
import { betterAuth } from "better-auth"
import { phoneNumber } from "better-auth/plugins"
export const auth = betterAuth({
plugins: [
phoneNumber({
sendOTP: async ({ phoneNumber, code }) => {
console.log(`Send ${code} to ${phoneNumber}`)
},
}),
],
})Creates the Better Auth server configuration with phone-number OTP delivery delegated to the callback.
When to use it
OTP phone verification
An application needs to prove control of a phone number before continuing.
Verification-driven sign-up
A product wants to create accounts after successful phone verification.
Phone number and password sign-in
Existing credential accounts should accept a phone number as the login identifier.
Interview questions
QWhat does the phone number plugin provide?
The plugin adds phone-number sign-up and sign-in to Better Auth and uses OTPs to verify numbers. Its sendOTP callback receives the phone number and generated code so the application can send the code through an SMS provider.
Follow-up: How would you enable client-side support? Configure the client with phoneNumberClient() from better-auth/client/plugins.
QHow is OTP delivery configured?
Register phoneNumber in the server's plugins array and provide a sendOTP callback. The callback should deliver the received code to the supplied phone number.
Follow-up: What database preparation is required? Run the migration or generate the schema after installing the plugin.
QHow does OTP verification support sign-up?
The documented verification flow sends an OTP through the sendVerificationCode endpoint, then verifies the number with the supplied code. Phone-number sign-up can be enabled with signUpOnVerification.
Follow-up: What additional option is needed for that sign-up mode? Supply getTempEmail to generate the user's temporary email.
Related
phoneNumberClientsendVerificationCodesignUpOnVerificationgetTempEmail