Admin regenerate recovery codes (SUPER only)
Auth
Admin regenerate recovery codes (SUPER only)
Atomically replace the admin’s MFA recovery-code array with 10 fresh codes. Returns the raw codes ONCE. Requires SUPER role + re-auth.
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.
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
| Field | Type | Required | Notes | Example |
|---|---|---|---|---|
currentPassword | string | yes | 1..200 chars. Verified server-side against the stored argon2 hash. Same enumeration-safe ADMIN_INVALID_CREDENTIALS surface as login. | correct-horse-battery-staple |
Example payload
Response — 200 OK
| Field | Type | Notes |
|---|---|---|
codes | string[] | Exactly 10 raw recovery codes. Format ABCD-EFGH-IJKL. Returned once — store them now. |
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | currentPassword empty or longer than 200 chars. |
| 401 | UNAUTHENTICATED | Missing / malformed / expired admin token. |
| 401 | ADMIN_INVALID_CREDENTIALS | The supplied currentPassword is wrong. |
| 403 | FORBIDDEN | Caller is a MODERATOR or FINANCE admin. SUPER only. |
| 429 | RATE_LIMITED | Burst limiter tripped (10/min/IP). |
Example error — 403 FORBIDDEN
Side effects
| Effect | Notes |
|---|---|
| Recovery code array | Atomically replaced. Old codes are immediately invalid. |
| Refresh tokens | Unchanged. This endpoint does NOT log other devices out. |
| Audit row | action: admin.recovery-codes-regenerated, actorType: ADMIN. |
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
- Admin auth and MFA — the full login + MFA story, including the 10 codes’ role.
- Admin MFA recovery — use a single code.
- Change password — independent of recovery codes.
curl
Postman
Seedocs/postman/swappr.postman_collection.json → Admin Auth → Regenerate Recovery Codes.