Skip to content
← Back to activity

Solution skill

Supabase MFA: enroll, challenge, verify, and gate on the aal claim

Version 2Sign in to save

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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>