Admin regenerate recovery codes (SUPER only)
curl --request POST \
--url https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerateimport requests
url = "https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyAuth
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
/
api
/
v1
/
admin
/
auth
/
mfa-recovery
/
regenerate
Admin regenerate recovery codes (SUPER only)
curl --request POST \
--url https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerateimport requests
url = "https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/admin/auth/mfa-recovery/regenerate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyOverview
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.
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
| 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
{
"currentPassword": "correct-horse-battery-staple"
}
Response — 200 OK
| Field | Type | Notes |
|---|---|---|
codes | string[] | Exactly 10 raw recovery codes. Format ABCD-EFGH-IJKL. Returned once — store them now. |
{
"codes": [
"ABCD-EFGH-IJKL",
"MNOP-QRST-UVWX",
"YZ12-3456-7890",
"ABCD-EFGH-IJKL",
"MNOP-QRST-UVWX",
"YZ12-3456-7890",
"ABCD-EFGH-IJKL",
"MNOP-QRST-UVWX",
"YZ12-3456-7890",
"ABCD-EFGH-IJKL"
]
}
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
{
"type": "https://api.swappr.co.uk/errors/forbidden",
"title": "Forbidden",
"status": 403,
"code": "FORBIDDEN",
"detail": "Admin role MODERATOR is not permitted for this action",
"instance": "/api/v1/admin/auth/mfa-recovery/regenerate",
"requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}
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
curl -X POST https://api.swappr.co.uk/api/v1/admin/auth/mfa-recovery/regenerate \
-H "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"currentPassword":"correct-horse-battery-staple"}'
Postman
Seedocs/postman/swappr.postman_collection.json → Admin Auth → Regenerate Recovery Codes.