Phone Number Authentication#

The phoneNumber plugin (id: "phone-number") adds phone-based sign-in, OTP verification, and password reset flows to better-auth. It lives in packages/better-auth/src/plugins/phone-number/ and registers five HTTP endpoints. See the official docs for setup and client-side usage.

Schema#

The plugin extends the user table with two fields 1:

Phone numbers cannot be updated directly via /update-user — changing phoneNumber to a non-null value is blocked by a before hook 2. Setting it to null (disassociation) is allowed and automatically resets phoneNumberVerified to false via a database hook 3.

Endpoints#

All five endpoints are defined in routes.ts and registered in index.ts:

Sign-In Flow (/sign-in/phone-number)#

Accepts { phoneNumber, password, rememberMe? } 4.

1. Optional phoneNumberValidator runs first 5.
2. Looks up the user by phoneNumber; looks up their credential account for password verification 6.
3. If requireVerification: true and phoneNumberVerified is false, a fresh OTP is sent and the request is rejected with PHONE_NUMBER_NOT_VERIFIED 7.
4. On success, calls internalAdapter.createSession(userId, rememberMe === false) — passing true as the second arg disables the extended session TTL 8.
5. Sets the session cookie via setSessionCookie, also forwarding the rememberMe flag.

OTP Send and Verify Flow#

Sending (/phone-number/send-otp)#

Generates an OTP with generateRandomString(otpLength, "0-9") 9 and stores it as "{code}:0" — the suffix is the attempt counter — via internalAdapter.createVerificationValue 10. The sendOTP callback is dispatched in the background if a background-task handler is configured 11.

Verifying (/phone-number/verify)#

Accepts { phoneNumber, code, disableSession?, updatePhoneNumber? }.

• Custom provider path: If verifyOTP is configured, it delegates to that callback and then cleans up the stored verification value 12.
• Built-in path: Calls verifyPhoneNumberOTP (described below).

After successful OTP verification:

• If updatePhoneNumber: true and a session exists, updates the current user's phone number and marks it verified 13.
• Otherwise, looks up (or creates via signUpOnVerification) the user and marks phoneNumberVerified: true 14.
• Creates a session unless disableSession: true 15.
• Fires callbackOnVerification after any update 16.

signUpOnVerification#

When set, a user without an existing account is created with a temporary email (getTempEmail(phoneNumber)) and optional name (getTempName?) 17. This enables a fully passwordless phone-number signup flow.

Atomic OTP Verification & Rate Limiting#

Attempt Tracking and Atomic Consumption#

The verifyPhoneNumberOTP function is the race gate for all OTP checks (including password reset). Key design points:

1. Attempt check: Before consuming the row, it reads the attempt count from the stored "{code}:{attempts}" value. If attempts >= allowedAttempts (default 3), the row is deleted and TOO_MANY_ATTEMPTS is thrown 18.
2. Atomic consume: Calls internalAdapter.consumeVerificationValue(identifier) — this atomically deletes-and-returns the row. The first concurrent caller wins; any racer getting null is rejected with INVALID_OTP 19.
3. Wrong code: If the code doesn't match, the row is recreated with an incremented attempt count and the original expiry 20. Once allowedAttempts is reached, the row is not recreated.

The attempt counter is stored in-band with the OTP value ("{otp}:{n}") so it persists across recreations without an extra DB column.

Rate Limiting#

The plugin registers a rate limit rule for all /phone-number/* paths: 10 requests per 60-second window 21. Note: /sign-in/phone-number does not match this pattern and relies on the global rate limiter.

Password Reset via Phone#

• Request (/phone-number/request-password-reset): Generates an OTP stored under key "{phoneNumber}-request-password-reset" and calls sendPasswordResetOTP. Always returns { status: true } regardless of whether the phone number exists, preventing enumeration 22.
• Reset (/phone-number/reset-password): Verifies OTP using the same verifyPhoneNumberOTP function (with the prefixed identifier), then creates or updates the credential account password. Respects revokeSessionsOnPasswordReset if configured 23.

Configuration Reference#

All options are defined in types.ts. Key options:

Key Source Files#