Enroll an MFA factor (TOTP)
/v1/auth/mfa/setupGenerates a TOTP secret and the corresponding otpauth:// URL for the user carried by the JWT. The request has no body: the user comes from the token.
Headers
| Header | Required | Value |
|---|---|---|
apikey | yes | Clé API du projet |
Authorization | yes | Bearer <JWT utilisateur> — l'enrôlement porte sur l'utilisateur du token |
Available factors
This route enrolls the TOTP factor (it takes no factor_type). Two other second factors have their own endpoints; all three produce an aal2 session and share the same recovery codes:
| Factor | Enroll | Complete a sign-in challenge | amr |
|---|---|---|---|
| TOTP | POST /mfa/setup then POST /mfa/setup/verify | POST /mfa/verify-login with { mfa_token, code } | mfa:totp |
| Passkey (WebAuthn) | POST /mfa/webauthn/register/start then /register/finish | POST /mfa/webauthn/verify/start then /verify/finish with { mfa_token, credential } | mfa:webauthn |
| SMS | POST /mfa/sms/setup then /mfa/sms/setup/verify with { code } | POST /mfa/sms/send with { mfa_token }, then POST /mfa/verify-login with { mfa_token, sms_code } | mfa:sms |
POST /mfa/factors with { mfa_token } lists the factors a sign-in challenge accepts (totp, webauthn, sms). In the SDK: auth.mfa.factors(mfaToken), auth.mfa.webauthn.register() / .verify({ mfaToken }), auth.mfa.sms.setup(phone) / .verifySetup(code) / .send(mfaToken).
Passkeys are bound to the domain of the page that calls navigator.credentials: the request Origin must be the project's Site URL or one of its redirect URLs, and it must be a domain name (not an IP address). SMS needs an SMS provider or a send_sms hook configured on the project.
Activation
The secret remains waiting for until a successful POST /v1/auth/mfa/setup/verify with { "code": "123456" }. This confirmation returns 8 single-use recovery codes, displayable only once. Then, a login to this account responds mfa_required and must be finalized with POST /v1/auth/mfa/verify-login. Disable: /mfa/disable; code regeneration: /mfa/recovery-codes/regenerate.