Phone Number

The phone number plugin extends the authentication system by allowing users to sign in and sign up using their phone number. It includes OTP (One-Time Password) functionality to verify phone numbers.

Installation

import { betterAuth } from "better-auth"
import { phoneNumber } from "better-auth/plugins"
 
const auth = betterAuth({
    plugins: [ 
        phoneNumber({  
            sendOTP: (phoneNumber, code) => { 
                // Implement sending OTP code via SMS
            } 
        }) 
    ] 
})

npx @better-auth/cli migrate

import { createAuthClient } from "better-auth/client"
import { phoneNumberClient } from "better-auth/client/plugins"
 
const client = createAuthClient({
    plugins: [ 
        phoneNumberClient() 
    ] 
})

Usage

Send OTP for Verification

To send an OTP to a user's phone number for verification, you can use the sendVerificationCode endpoint.

await client.phoneNumber.sendOtp({
    phoneNumber: "+1234567890"
})

Verify Phone Number

After the OTP is sent, users can verify their phone number by providing the code.

const isVerified = await client.phoneNumber.verify({
    phoneNumber: "+1234567890",
    code: "123456"
})

Allow Sign-Up with Phone Number

to allow users to sign up using their phone number, you can pass signUpOnVerification option to the your plugin configuration. It reqiures you to pass getTempEmail function to generate a temporary email for the user.

export const auth = betterAuth({
    plugins: [
        phoneNumber({
            sendOTP: (phoneNumber, code) => {
                // Implement sending OTP code via SMS
            },
            signUpOnVerification: {
                getTempEmail: (phoneNumber) => {
                    return `${phonNumber}@my-site.com`
                },
                //optionally you can alos pass `getTempName` function to generate a temporary name for the user
                getTempName: (phoneNumber) => {
                    return phoneNumber //by default it will use the phone number as the name
                }
            }
        })
    ]
})

Update Phone Number

Updating phone number uses the same process as verifying a phone number. The user will receive an OTP code to verify the new phone number.

await client.phoneNumber.sendOtp({
    phoneNumber: "+1234567890" // New phone number
})

Then verify the new phone number with the OTP code.

const isVerified = await client.phoneNumber.verify({
    phoneNumber: "+1234567890",
    code: "123456",
    updatePhoneNumber: true // Set to true to update the phone number
})

if user session exist the phone number will be updated automatically

Disable Session Creation

By default, the plugin creates a session for the user after verifying the phone number. You can disable this behavior by passing disableSession: true to the verify method.

const isVerified = await client.phoneNumber.verify({
    phoneNumber: "+1234567890",
    code: "123456",
    disableSession: true
})

Options

• otpLength: The length of the OTP code to be generated. Default is 6.
• sendOTP: A function that sends the OTP code to the user's phone number. It takes the phone number and the OTP code as arguments.
• verifyOTP: A custom function to verify the OTP code. It takes the phone number and the OTP code as arguments and returns a boolean indicating whether the code is valid.
• expiresIn: The time in seconds after which the OTP code expires. Default is 300 seconds.
• phoneNumberValidator: A custom function to validate the phone number. It takes the phone number as an argument and returns a boolean indicating whether the phone number is valid.
• signUpOnVerification: An object with the following properties:
  • getTempEmail: A function that generates a temporary email for the user. It takes the phone number as an argument and returns the temporary email.
  • getTempName: A function that generates a temporary name for the user. It takes the phone number as an argument and returns the temporary name.

Schema

The plugin requires 2 fields to be added to the user table

User Table