POST
Admin regenerate recovery codes (SUPER only)

Overview

Replaces the calling admin’s MFA recovery-code array with 10 fresh codes. Used when:
  • The operator has burned through too many recovery codes and wants a clean set.
  • A recovery-code printout is suspected to be compromised — regenerating invalidates all old codes atomically.
The 10 raw codes are returned once in the response body. There is no second chance — the server only stores the argon2 hashes. Store them now (a printout, a password manager, a sealed envelope in the safe) or lose them. Losing all 10 plus the TOTP device is an irreversible lockout — the admin’s only recovery path then is another SUPER admin resetting their MFA via direct DB intervention.
Role-gated: SUPER only. Neither MODERATOR nor FINANCE may invoke it. The reasoning mirrors erasure: destructive operations that can lock an operator out are tightly scoped.Requires the current password as defense in depth, even though the caller is already authenticated.

Authentication

Bearer <accessToken> with scope: 'admin' AND role SUPER required. The endpoint is also covered by the 10-requests-per-minute-per-IP burst limiter to prevent a compromised access token churning the code array.

Path parameters

None.

Query parameters

None.

Request body

Example payload

Response — 200 OK

Error responses

Example error — 403 FORBIDDEN

Side effects

This is atomic — there is no transient window in which both the old codes and the new codes are valid. If the operation fails halfway (e.g. a hash write throws), the array is left unchanged and the response is a 500. Re-calling is safe.

See also

curl

Postman

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