convex-auth with phone

[hazy hare]

How to do auth with convex-auth using the phone number please

[normal pawn]

Hi @hazy hare. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

To implement authentication with Convex Auth using a phone number (SMS OTP), you need to configure a phone provider. Convex Auth does not include built-in phone providers, but you can easily build one using a service like Twilio.

Steps to Set Up Phone Number Authentication

1. Create a Phone Provider

   Use the Phone provider from Convex Auth. You need to implement the sendVerificationRequest function to send the OTP via SMS. Here’s a high-level outline:

   import { Phone } from "@convex-dev/auth/providers/Phone";
   import twilio from "twilio";
   
   export const TwilioOTP = Phone({
     id: "twilio-otp",
     maxAge: 60 * 15, // 15 minutes
     async sendVerificationRequest({ identifier: phone, token }) {
       const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
       await client.messages.create({
         body: `Your code is ${token}`,
         from: process.env.TWILIO_PHONE_NUMBER,
         to: phone,
       });
     },
   });
   

2. Add the Provider to Your Auth Config

   In your convex/auth.ts:

   import { convexAuth } from "@convex-dev/auth/server";
   import { TwilioOTP } from "./TwilioOTP";
   
   export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
     providers: [TwilioOTP],
   });
   

3. Frontend Sign-In Flow

   The sign-in form should collect the user's phone number and handle the OTP input. You can refer to the example repo’s phone sign-in form for implementation details.

4. Account Linking and User Management

Convex Auth will track sign-ups via phone in the authAccounts table. If you want to link phone-based accounts with other methods (like email), see the account linking documentation.

References

• Phone provider API reference
• Twilio OTP example
• Phone provider config details
• Configuring OTPs

If you need a ready-to-use solution with less setup, you can also consider using Better Auth which supports phone number authentication out of the box.

Let me know if you need a more detailed code example or help with a specific step!

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: