POST
Admin MFA recovery (lost device)

Overview

When the admin’s authenticator app is lost, broken, or otherwise unavailable, the operator falls back to one of the 10 single-use recovery codes that were printed on first MFA enrollment (and replaceable via regenerate). This endpoint replaces the TOTP step of the two-step login flow with a recovery code:
  • The user side still authenticates by email + password — same enumeration-safe ADMIN_INVALID_CREDENTIALS surface as /admin/auth/login.
  • Instead of presenting an mfaTicket + 6-digit TOTP, the caller presents a recovery code directly.
On success the recovery code is consumed (single-use) and a full admin token pair (access + refresh) is issued exactly as if the TOTP step had passed.
A recovery code is single-use. Consumed codes are gone — after a successful call the user has 9 left. When the count gets low, the operator should request a SUPER admin to regenerate the array.

Authentication

None. This is the recovery path — the caller IS authenticating. The endpoint is covered by the 10-requests-per-minute-per-IP burst limiter to prevent code-grinding.

Path parameters

None.

Query parameters

None.

Request body

Example payload

Response — 200 OK

Error responses

Example error — 401 MFA_INVALID_CODE

Side effects

Consuming a recovery code does not invalidate the operator’s TOTP device. If the user later finds their authenticator, they can resume using /admin/auth/mfa-verify — only the specific code that was used is gone.

See also

curl

Postman

See docs/postman/swappr.postman_collection.json → Admin Auth → MFA Recovery.