Platform
Multi-factor authentication
Tested with:supabase-js 2 · @supabase/auth-js 2.117
Your users can add a second factor to their account. The API is Supabase Auth’s, so supabase.auth.mfa.* works
unchanged: enroll, challenge, verify, challengeAndVerify, unenroll, listFactors and
getAuthenticatorAssuranceLevel.
Factors
Section titled “Factors”| Factor | Default | Notes |
|---|---|---|
| Authenticator app (TOTP) | on | Any RFC 6238 app (SHA-1, 30 s, 6 digits). enroll returns the secret and a QR code. |
| SMS (phone) | off | The code goes through your SMS provider or your send_sms hook (phone sign-in); the number must be in the project’s allowed countries. |
| Recovery codes | on | Ten single-use codes (mfa.recoveryCodes) for a user who lost their device. |
| WebAuthn (security keys, passkeys) | off | A second factor bound to your app’s domain (below). Turn it on and set the relying party in Platform services → Auth → MFA. |
A user may hold up to max_enrolled_factors factors (10 by default, at most 20).
Enrol and verify
Section titled “Enrol and verify”const { data: factor } = await supabase.auth.mfa.enroll({ factorType: "totp", friendlyName: "Phone app" });// Show factor.totp.qr_code; then, with the 6-digit code the user types:const { data: challenge } = await supabase.auth.mfa.challenge({ factorId: factor.id });await supabase.auth.mfa.verify({ factorId: factor.id, challengeId: challenge.id, code });A verified code raises the session to aal2: the access token’s aal claim says so and amr lists the methods used.
Use it in row-level security to protect sensitive tables:
create policy "aal2 for payouts" on payouts as restrictive for all to authenticated using ((auth.jwt() ->> 'aal') = 'aal2');WebAuthn
Section titled “WebAuthn”Security keys, Touch ID, Windows Hello and passkeys work as a second factor with supabase-js’s WebAuthn helpers:
// Register a key (enrol + challenge + browser ceremony + verify); the session reaches aal2.await supabase.auth.mfa.webauthn.register({ friendlyName: "YubiKey" });// Later, on a fresh aal1 session:await supabase.auth.mfa.webauthn.authenticate({ factorId });The relying party is your app, not Databasezy. Set it before turning the factor on:
zb api PUT /v1/orgs/{org}/projects/<project-id>/auth/mfa -d '{ "web_authn": { "enroll_enabled": true, "verify_enabled": true, "rp_id": "example.com", "rp_origins": ["https://app.example.com", "https://admin.example.com"] }}'rp_idis the domain your app’s pages share (empty: your site URL’s host). Keys are bound to it: changing it later makes registered keys stop working.rp_originsare the exact origins allowed to run a ceremony (empty: your site URL’s origin), up to 10,httpsonly (http://localhostfor local development), onrp_idor a subdomain.- supabase-js sends
window.locationasrpId/rpOrigins; the server only narrows to what you configured. An rp id or origin you did not list answers422 mfa_webauthn_origin_not_allowed/mfa_webauthn_rp_not_allowed, and a response collected at another origin fails verification; both are security events in your audit log. - Attestation is
noneand user verificationpreferred, so any FIDO2 key or platform authenticator works. - Each challenge is single use and expires with
challenge_expiry; a new challenge replaces the factor’s open one. - The authenticator’s signature counter must grow. A counter that goes backwards means a cloned key: verification
answers
422 mfa_verification_rejected, the factor stays refused until the user (ataal2) or an admin removes it, and a high-severity security event is recorded. Synced passkeys that always report 0 are accepted. - One key is one user’s factor: registering a key another user already registered answers
mfa_webauthn_credential_exists. A user may hold up to 10 WebAuthn factors (withinmax_enrolled_factors). - Passkey sign-in as a first factor (
signInWithPasskey) is a different Supabase feature and is not served yet.
Project policy
Section titled “Project policy”Set the policy in Platform services → Auth → MFA or with the API:
zb api PUT /v1/orgs/{org}/projects/<project-id>/auth/mfa -d '{ "enforcement": "required", "phone": { "enroll_enabled": true, "verify_enabled": true }}'optional(default): users choose; sessions start ataal1.required: the project endpoint refuses your users’aal1tokens on every path except/auth/v1, so a user can still enrol or verify a factor but reaches the data API (including GraphQL and query routes), storage, realtime and functions only after it. API keys and third-party tokens are not affected.
What is enforced
Section titled “What is enforced”- Single use: a TOTP code is accepted once (the last time step is stored); an SMS code belongs to one challenge;
a challenge expires after
challenge_expiry(300 s) and must be verified from the IP that opened it. - Guessing: five wrong codes in a row lock the factor for 15 minutes, and challenge and verify are limited per
client IP (
rate_limit, 30 per 5 minutes). A lock is a security event in your audit log. - Sensitive changes: with a verified factor, changing the email, phone or password and removing a verified factor
need an
aal2session. Verifying signs out the user’s otheraal1sessions. - Hooks: the
mfa_verification_attempthook runs on every verification and can reject it. - Admins list and remove a user’s factors from the Users page or
GET/DELETE /auth/v1/admin/users/{id}/factors.