Benutzer-MFA zurücksetzen

POST /api/users/:id/mfa/reset

Ein Organisations-Admin (oder Global Admin) kann die Zwei-Schritt-Bestätigung eines anderen Benutzers erzwungen zurücksetzen. Dabei wird der gespeicherte zweite Faktor des Benutzers gelöscht und twoFactorEnabled für dessen Konto deaktiviert — es wird kein neuer Faktor eingerichtet. Der Benutzer erhält eine Benachrichtigung per E-Mail und muss die Zwei-Schritt-Bestätigung beim nächsten Mal, wenn sie verlangt wird, erneut einrichten.

Den eigenen zweiten Faktor kannst du über diesen Endpoint nicht zurücksetzen. Das Entfernen des eigenen Faktors läuft über die Sicherheitseinstellungen des Kontos und erfordert dein Passwort.

API-Tokens können diesen Endpoint nicht aufrufen. Er erfordert eine echte, eingeloggte Benutzer-Session (ein Organisations-Admin oder Global Admin) — ein Authorization: Bearer API-Token wird immer abgelehnt, auch ein organisations-gescoptes Token mit Admin-Rechten. Das gilt ebenso für Agent-Access-Tokens. Ein geleaktes Token darf niemals in der Lage sein, den MFA-Schutz einer Organisation auszuhebeln, indem es die Faktoren der Mitglieder nacheinander zurücksetzt.

Anfrage (Request Body)

Keiner.

Beispiel (cURL)

Ruf diesen Endpoint aus einer authentifizierten Browser-Session heraus auf (dem eigenen Login-Session-Cookie des Admins), nicht mit einem API-Token:

BASE_URL="https://uptimeify.io"

curl -X POST "$BASE_URL/api/users/user_123/mfa/reset" \
  -H "Cookie: better-auth.session_token=<dein-session-cookie>" \
  -H "Accept: application/json"

Antwort (Response)

{ "ok": true }

Häufige Fehler

• 401 unauthorized wenn du nicht authentifiziert bist
• 403 nonUserSessionForbidden bei Aufruf mit einem API-Token oder Agent-Access-Token statt einer echten Benutzer-Session — siehe oben
• 403 customerScopedTokenForbidden bei Aufruf mit einem kunden-gescopten API-Token; dies ist eine organisationsweite Aktion und erfordert ein organisations-gescoptes Token oder eine Session
• 404 userNotFound wenn sich :id keinem Benutzer zuordnen lässt
• 403 insufficientPermissions wenn der Aufrufer den zweiten Faktor dieses Benutzers nicht zurücksetzen darf — siehe unten

Berechtigungsregeln (data.code: insufficientPermissions):

• Den eigenen zweiten Faktor kannst du über diesen Endpoint niemals zurücksetzen.
• Global Admins können jeden Benutzer zurücksetzen.
• Global Supporter (nur lesender Zugriff über alle Organisationen hinweg) können niemals einen Benutzer zurücksetzen.
• Organisations-Admins können nur Benutzer innerhalb der eigenen Organisation zurücksetzen; der Zielbenutzer muss zur selben Organisation gehören wie der Aufrufer.
• Normale (Nicht-Admin-)Benutzer können den zweiten Faktor eines anderen Benutzers niemals zurücksetzen.