Email & Password

Email and password is the one auth method that is on from the moment floot create finishes. Every social provider and the second factor are layered on top of it, so this page is the prerequisite for all of them.

Codes, not links

The three templates render the code and nothing else: look at the {token} they each drop into a bordered box.

"Magic link" is therefore a slight misnomer here: it is a passwordless sign-in code. The naming comes from Supabase's magiclink email action. The magic link screen verifies the typed code as OtpType.email, which accepts any emailed sign-in code. That matters for an account that never confirmed its email: asking for a magic link sends it the sign-up confirmation email instead, and that code signs it in from the same screen.

Asking for a magic link with an email that has no account shows an error toast on the login page instead of a code screen waiting for an email that never comes.

The one exception: invites

The fourth Supabase email action, invite, is link-based. It is the only one that carries a URL, and it is verified through a tokenHash rather than a typed code. Sending invites is what Multi-tenancy only adds; the verification path itself is present in every project. The invitation flow itself is on Members & Invites.

Password rules are stricter in the app than in the database

The Flutter validator (lib/core/presentation/utils/validators/password.dart) defaults to 12 characters, plus at least one lowercase letter, one uppercase letter, one digit and one of !@#$%^&*. Supabase's own floor is lower: minimum_password_length = 8, so the app is the binding constraint. Loosen the validator by passing different arguments to Password.dirty(...) in sign_up_cubit.dart and pwd_reset_cubit.dart; tighten the server in supabase/config.toml. Changing one without the other just moves where the rejection happens.

How the email actually gets sent

Supabase does not send these emails. A send-email hook intercepts every auth email and hands it to an Edge Function, which renders the React Email template and posts it over SMTP.

[auth.hook.send_email]
enabled = true
uri = "http://host.docker.internal:54321/functions/v1/send-email"
secrets = "env(SB_SEND_EMAIL_HOOK_SECRET)"

The hook signs its request with SB_SEND_EMAIL_HOOK_SECRET, and supabase/functions/send-email/_utils/email_processor.ts verifies that signature before doing anything, which is why [functions.send-email] sets verify_jwt = false: the standardwebhooks signature is the authentication, not a JWT.

The SMTP environment set

Five variables live in supabase/.env.local. All five are unconditionally required: unlike the Stripe and RevenueCat keys, none of them is gated behind an ENABLE_* flag.

SMTP_FROM: z.string().min(1),
SMTP_HOST: z.string().min(1),
SMTP_PASSWORD: z.string().min(1),
SMTP_PORT: z.coerce.number().min(1),
SMTP_USER: z.string().min(1),

env.ts parses the environment at module load and throws if anything is missing, and every Edge Function imports it transitively. A missing SMTP variable does not break email; it stops the whole function runtime from booting.

A blank value counts as missing: env.ts strips empty strings before validating, precisely so that KEY= reads as "not provided" for the optional keys.

Filled in for local development, the block reads:

SMTP_FROM="My App <noreply@acme.com>"
SMTP_HOST=host.docker.internal
SMTP_PASSWORD=mailpit
SMTP_PORT=54325
SMTP_USER=mailpit

host.docker.internal rather than 127.0.0.1 because the Edge Function runs inside a container and has to reach back out to the host. Port 54325 is Mailpit's SMTP listener; the number you see in the supabase start banner, 54324, is its web UI.

Reading the mail

Nothing leaves your machine locally. Every email the project sends, auth codes, the password-changed notice, invitations, is caught by Mailpit at http://127.0.0.1:54324. Open it side by side with the app and copy the code out of the message.

Both ports come from supabase/config.toml:

[local_smtp]
enabled = true
port = 54324
smtp_port = 54325

Moving to a real provider

For real mail, point the same five variables at your provider (Resend, SendGrid, Postmark, SES, anything that speaks SMTP). You can try them locally in supabase/.env.local. On your deployed backend they are function secrets like the others, never in a file the app bundles: set with supabase secrets set on Supabase Cloud (see Mail), and as environment on the functions service when self-hosted (see Function secrets).

SMTP_FROM="My App <noreply@myapp.com>"
SMTP_HOST=smtp.resend.com
SMTP_PASSWORD="<your api key>"
SMTP_PORT=587
SMTP_USER=resend

secure: env.SMTP_PORT === 465 ? true : false,

The settings behind these flows

Everything above is driven by two blocks in supabase/config.toml. These are the values a generated project ships with, and the ones worth understanding before you change any of them.

[auth], account-level policy:

[auth.email], the email flows specifically:

Three further notifications also ride the same hook and are on by default: [auth.email.notification.password_changed], [auth.email.notification.mfa_factor_enrolled] and [auth.email.notification.mfa_factor_unenrolled]. They are security notices, not codes, and nothing in the app has to handle them.

Rate limits you will hit

Two numbers in supabase/config.toml decide how often a user can ask for an email, and both surface in the app as the same toast: "Too many requests. Please try again later." There is no countdown and no distinct message: a 429 from GoTrue becomes TooManySignUpRequests, TooManyPwdReq, TooManyLoginRequests or EmailTooManyRequests, and every one of them maps to l10n.tooManyRequests.

[auth.rate_limit]
email_sent = 60

[auth.email]
max_frequency = "45s"

The OTP screen's own 60-second resend cooldown sits deliberately above the 45 second server gap, so the Resend button never trips the limit on its own. What trips it is re-submitting the sign-up form, or requesting a password reset two or three times in a row while wondering where the email went.

Users cannot link a second sign-in method

enable_manual_linking = false

With manual linking off, GoTrue rejects linkIdentity and unlinkIdentity outright, which makes the account's identity list read-only for the whole lifetime of the account. The set of providers on a user is whatever Supabase attached automatically: password on sign-up, plus any social provider that matched on a verified email address.

So a "Connect your Google account" button is not a UI you can simply build: it needs enable_manual_linking = true (and the same setting on your deployed backend: the matching Auth setting in the Supabase Cloud dashboard, or GOTRUE_SECURITY_MANUAL_LINKING_ENABLED: "true" on a self-hosted auth service) before the API calls behind it will succeed. Flipping it on is a security decision as much as a feature one, letting a signed-in session attach arbitrary identities to an account widens what a stolen session can do, so it ships off.

What's next