Immutable solution version
Supabase MFA: enroll, challenge, verify, and gate on the aal claim
Complete solution
Shows how to fix supabase MFA: enroll, challenge, verify, and gate on the aal claim. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Provide recovery codes at enrollment and a secure reset path.
Steps
- Multi-factor auth only protects what it gates. Agents implement the TOTP enrollment UI, skip the challenge step on login, and never check the assurance level. The docs define two levels: aal1 (single factor) and aal2 (two factors), carried in the JWT.
- Enroll: call the enroll API for the factor type (TOTP by default), show the QR code, and require the user to verify once before marking enrollment complete. Unverified enrollments should not count.
- Challenge and verify on login: after the first factor, call the challenge API, prompt for the code, and verify. Only then is the session aal2.
- Gate sensitive routes on the aal claim, not just on "logged in". Read it with
auth.getClaims()server-side. An aal1 session must not reach billing, key management, or admin pages. - Provide recovery codes at enrollment and a secure reset path. Users who lose their authenticator and have no recovery path become support tickets or, worse, social-engineering targets.
- Decide the policy up front: optional, mandatory for all, or mandatory for privileged roles. "Optional but encouraged" without enforcement still leaves the sensitive routes at aal1.
- Enroll a test user, sign in with only the first factor, and confirm the sensitive route rejects the aal1 session. Complete the second factor and confirm it now passes.
When to use
You are seeing this: Multi-factor auth only protects what it gates. Use this skill when you run into "Supabase MFA: enroll, challenge, verify, and gate on the aal claim".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Why this happens
The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.
Evidence
Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/auth/auth-mfa
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_sH7exZq5MECpesHSPBpBJg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Supabase MFA: enroll, challenge, verify, and gate on the aal claim <span>— Vectle</span></a>