Skip to content

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.

FactorDefaultNotes
Authenticator app (TOTP)onAny RFC 6238 app (SHA-1, 30 s, 6 digits). enroll returns the secret and a QR code.
SMS (phone)offThe 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 codesonTen single-use codes (mfa.recoveryCodes) for a user who lost their device.
WebAuthn (security keys, passkeys)offA 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).

app/mfa.ts
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:

SQL
create policy "aal2 for payouts" on payouts
as restrictive for all to authenticated
using ((auth.jwt() ->> 'aal') = 'aal2');

Security keys, Touch ID, Windows Hello and passkeys work as a second factor with supabase-js’s WebAuthn helpers:

app/webauthn.ts
// 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:

shell
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_id is 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_origins are the exact origins allowed to run a ceremony (empty: your site URL’s origin), up to 10, https only (http://localhost for local development), on rp_id or a subdomain.
  • supabase-js sends window.location as rpId / rpOrigins; the server only narrows to what you configured. An rp id or origin you did not list answers 422 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 none and user verification preferred, 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 (at aal2) 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 (within max_enrolled_factors).
  • Passkey sign-in as a first factor (signInWithPasskey) is a different Supabase feature and is not served yet.

Set the policy in Platform services → Auth → MFA or with the API:

shell
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 at aal1.
  • required: the project endpoint refuses your users’ aal1 tokens 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.
  • 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 aal2 session. Verifying signs out the user’s other aal1 sessions.
  • Hooks: the mfa_verification_attempt hook 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.