Admin MFA recovery (lost device)
curl --request POST \
--url https://api.example.com/api/v1/admin/auth/mfa-recoveryimport requests
url = "https://api.example.com/api/v1/admin/auth/mfa-recovery"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/admin/auth/mfa-recovery', 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",
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"
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")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/admin/auth/mfa-recovery")
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 MFA recovery (lost device)
Use a single-use recovery code to recover admin access when the operator has lost their authenticator device. Issues a fresh admin token pair.
POST
/
api
/
v1
/
admin
/
auth
/
mfa-recovery
Admin MFA recovery (lost device)
curl --request POST \
--url https://api.example.com/api/v1/admin/auth/mfa-recoveryimport requests
url = "https://api.example.com/api/v1/admin/auth/mfa-recovery"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/admin/auth/mfa-recovery', 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",
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"
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")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/admin/auth/mfa-recovery")
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
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_CREDENTIALSsurface as/admin/auth/login. - Instead of presenting an mfaTicket + 6-digit TOTP, the caller presents a recovery code directly.
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
| Field | Type | Required | Notes | Example |
|---|---|---|---|---|
email | string | yes | Valid email, 5..254 chars. Lower-cased server-side. | admin@swappr.co.uk |
password | string | yes | 1..200 chars. The current admin password. | correct-horse-battery |
recoveryCode | string | yes | 8..64 chars. Production format is ABCD-EFGH-IJKL (14 chars), but the surface accepts a broader range for future format flexibility. | ABCD-EFGH-IJKL |
deviceFingerprint | string | no | Opaque client fingerprint, max 512 chars. Stored on the new refresh token row. | fp_9a3c… |
Example payload
{
"email": "admin@swappr.co.uk",
"password": "correct-horse-battery",
"recoveryCode": "ABCD-EFGH-IJKL"
}
Response — 200 OK
| Field | Type | Notes |
|---|---|---|
accessToken | string | Admin access token, 15-min TTL, scope admin. |
refreshToken | string | Opaque refresh token, 7-day TTL. |
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "rt_a1b2c3d4e5f6..."
}
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | Any field missing or out of length bounds. |
| 401 | ADMIN_INVALID_CREDENTIALS | Email + password verification failed. Enumeration-safe — same code/timing whether the email is unknown or the password is wrong. |
| 401 | MFA_INVALID_CODE | The recovery code is unknown, already consumed, or otherwise invalid. The full argon2 verify cost is still paid so timing cannot distinguish “consumed” from “wrong”. |
| 429 | RATE_LIMITED | Burst limiter tripped (10/min/IP). |
Example error — 401 MFA_INVALID_CODE
{
"type": "https://api.swappr.co.uk/errors/mfa-invalid-code",
"title": "MFA code invalid",
"status": 401,
"code": "MFA_INVALID_CODE",
"detail": "Recovery code invalid or already used",
"instance": "/api/v1/admin/auth/mfa-recovery",
"requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}
Side effects
| Effect | Notes |
|---|---|
| Recovery code consumed | The matched code is removed from the admin’s recovery-code array atomically. Other codes are unaffected. |
| Refresh token row | New row inserted with deviceFingerprint and a fresh secret. |
| Audit row | action: admin.mfa-recovery, actorType: ADMIN. |
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
- Admin auth and MFA — the full login + MFA story.
- Admin login (step 1) / Verify MFA (step 2) — the normal happy-path login.
- Regenerate recovery codes — replace the 10 codes atomically (SUPER only).
curl
curl -X POST https://api.swappr.co.uk/api/v1/admin/auth/mfa-recovery \
-H "Content-Type: application/json" \
-d '{
"email": "admin@swappr.co.uk",
"password": "correct-horse-battery",
"recoveryCode": "ABCD-EFGH-IJKL"
}'
Postman
Seedocs/postman/swappr.postman_collection.json → Admin Auth → MFA Recovery.