Skip to main content

Configure phone sign-in

The website signs users up and in with SMS one-time codes from Supabase Auth. The API needs no SMS secret: it only reads the caller's confirmed phone with the project's publishable key. This guide covers the Supabase side.

Local development​

:::warning Local phone sign-in does not work yet

supabase/config.toml sets [auth.sms] enable_signup = true and defines test numbers under [auth.sms.test_otp] (380500000001 and 380500000002, both with the code 123456), but every SMS provider block is disabled. With this configuration, Supabase CLI v2.67.1 prints no SMS provider is enabled. Disabling phone login when it starts, so local Auth rejects phone code requests and the website reports phone sign-in as unavailable. Test numbers alone do not keep phone login on.

A working local setup has not been verified. Until it is, exercise phone sign-in against a hosted project, and use email and password sign-in locally.

:::

If you experiment with the local setup:

  • Restart local Supabase after changing supabase/config.toml so Auth reloads it, and check the startup output for the message above.
  • Add test numbers as lines such as 380500000003 = "123456". Write the number without +, the way Supabase stores it.
  • Keep provider credentials out of the file. The Twilio block reads its auth token from SUPABASE_AUTH_SMS_TWILIO_AUTH_TOKEN.

Hosted project​

You need dashboard access to the Supabase project and an account with an SMS provider.

  1. Choose a provider. Supabase supports Twilio, Twilio Verify, MessageBird, Vonage and Textlocal. Twilio Verify is the simplest choice: it generates and delivers codes and has built-in fraud protection by country.
  2. Enable the Phone provider. In the dashboard, open Authentication → Sign In / Providers → Phone. Turn on the Phone provider, select the SMS provider, and enter its credentials. Credentials stay in Supabase. Never put them in the API, the website or the repository.
  3. Allow sign-ups by phone. The website relies on the first verified code creating the user. Keep Enable phone confirmations on.
  4. Set code options. Use 6 digits and an expiry of 5 to 10 minutes.
  5. Limit sending. Under Authentication → Rate Limits, set an hourly SMS limit sized to expected sign-ups. If the provider supports it, allow only the countries you serve.
  6. Turn on CAPTCHA (recommended). Under Authentication → Attack Protection, enable Cloudflare Turnstile or hCaptcha. This limits SMS pumping, where bots trigger paid messages to premium numbers. When CAPTCHA is on, Supabase refuses code requests that have no CAPTCHA token. The website's auth layer can pass one, but the sign-in page has no CAPTCHA widget yet, so add one before you turn this on.
  7. Give the API the publishable key. Set SUPABASE_PUBLISHABLE_KEY on the API. Without it, POST /client/account answers 503. See Environment variables.
  8. Check the result. Sign in on the website with a real number, choose Create client account, and confirm it reports the account as ready.

Monitor and roll back​

  • Watch SMS volume and cost in the provider's console. A sudden rise in codes to unfamiliar country codes usually means SMS pumping.
  • To stop phone sign-ups quickly, turn off phone sign-ups (or the Phone provider) in the dashboard. Existing sessions keep working until they expire. Email sign-in is not affected.

Known limits​

  • Recycled numbers. Whoever controls a phone number can sign in as that number's Supabase user. Carriers reassign numbers, so a new owner can reach the previous owner's account.
  • No linking. A phone sign-in never links to or merges with a Telegram identity. See Website sign-in.