Skip to content
Auth

Test auth flows

Test email and phone sign-in without hitting email and SMS limits

Test sign-up, sign-in, and password recovery as often as you need without waiting on email or SMS limits. Develop against local Supabase to capture every email in Mailpit, and use test phone numbers to sign in with a fixed code.

The local development steps need the Supabase CLI and a project initialized with supabase init. To set them up, see Supabase CLI.

Test email flows locally#

The Supabase CLI sends every email from local Auth to Mailpit, an email testing server that runs with your local stack. No email leaves your machine, so you can send to any address. Local Auth has no hourly email limit. For more information about Mailpit, see the Mailpit repository on GitHub.

  1. In your project directory, run supabase start to start the local stack.

  2. Run supabase status to get your local stack's connection details. Copy the following values from the output:

    • Project URL: the local API URL, which is http://127.0.0.1:54321 by default
    • Publishable: the local publishable key, which starts with sb_publishable_
    • Mailpit: the Mailpit URL, which is http://127.0.0.1:54324 by default

  3. Connect your app to the local stack. Your app's Supabase client reads a project URL and a publishable key from environment variables, which usually hold your hosted project's values. Replace them with the Project URL and Publishable key you copied from supabase status:

    NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
    NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

    Variable names depend on your framework. To test against your hosted project again, restore its project URL and publishable key.

  4. In your app, request a magic link or a password recovery email.

  5. In your browser, go to the Mailpit URL and open the email to get the link or code.

Local Auth limits how often it sends to the same address. By default, it sends one email per address per second. To change this, set max_frequency under [auth.email] in supabase/config.toml.

Email confirmation is off by default in local development and on by default for hosted projects, so local sign-up doesn't send an email. To test the confirmation email locally, set enable_confirmations = true under [auth.email], and then restart the local stack.

Test email flows on a hosted project#

Hosted projects send email through a built-in email service until you set up custom SMTP. The built-in service is for trying out Auth, and it has the following limits:

  • It sends only to the email addresses of your organization's team members. Other addresses fail with the error code email_address_not_authorized.
  • It sends 2 emails per hour across the whole project while Confirm email is on. When the project reaches the limit, Auth returns a 429 error with the code over_email_send_rate_limit and the message email rate limit exceeded.

To send to any address and raise the limit, set up custom SMTP or the Send Email hook. You can then change the email limit in Authentication > Rate Limits. For more information about the limits, see Rate limits.

Test phone sign-in with test numbers#

With a test phone number, you sign in with a fixed one-time password (OTP) that you choose. Auth doesn't send an SMS to a test number, and it accepts the fixed code as many times as you need.

Test numbers work for phone sign-up, sign-in, and phone number changes. They don't apply to phone multi-factor authentication, which always sends a real SMS.

Before you add test numbers, enable the phone provider and configure an SMS provider. Auth requires an SMS provider even though it doesn't send anything to test numbers.

Write each phone number in international format, with the country code and without the + prefix or spaces. For example, write +1 415 555 2671 as 14155552671. Auth compares the number your app sends against this value, so a number without its country code doesn't match.

  1. Go to Authentication > Sign In / Providers, and open Phone.
  2. In Test Phone Numbers and OTPs, enter a comma-separated list of <phone number>=<OTP> pairs, such as 14155552671=123456.
  3. In Test OTPs Valid Until, choose when the test numbers stop working. The Dashboard requires this date.
  4. Click Save.

Test numbers don't count toward the project's hourly SMS limit. Auth makes you wait between codes for the same number. The wait defaults to 5 seconds. Locally, change it with max_frequency under [auth.sms].

For a full list of settings to check before launch, see the Production checklist.