Password Reset

POST /api/v1/auth/reset
Content-Type: application/json

Resets an operator’s password using the recovery token issued at registration. This is a public route — no session cookie required.

Password reset is recovery-token based, not email based — there is no mail server in this stack. The token issued once at registration is the proof.

Request

{
  "login": "alex.dev",
  "recoveryKey": "frostauth-rt-9a8b7c6d5e4f...",
  "password": "new-password-here",
  "twofa": "000000", // optional
  "hcaptchaToken": "P1_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Parameters

Field	Required	Description
`login`	Yes	Username or email address.
`recoveryKey`	Yes	The recovery token issued at registration. Compared via constant-time equality against a stored digest.
`password`	Yes	The new password. Minimum 8 characters.
`twofa`	Conditional	TOTP or recovery code. Required if the account has 2FA enabled — a reset is not a way around the second factor.
`hcaptchaToken`	Conditional	hCaptcha response token from the reset form. Only present when `NEXT_PUBLIC_HCAPTCHA_SITE_KEY` is configured.

Responses

{
  "success": true,
  "response": {
    "data": {
      "reset": true,
      "recoveryKey": "frostauth-rt-NEW_ROTATED_KEY...",
      "sessionsRevoked": true
    }
  }
}

{
  "error": true,
  "response": {
    "code": 400,
    "message": "All fields are required"
  }
}

{
  "error": true,
  "response": {
    "code": 401,
    "message": "That recovery key is not valid for this account"
  }
}

{
  "error": true,
  "response": {
    "code": 403,
    "message": "Account is inactive or suspended"
  }
}

{
  "error": true,
  "response": {
    "code": 429,
    "message": "Too many reset attempts, try again later"
  }
}

{
  "error": true,
  "response": {
    "code": 500,
    "message": "Failed to reset the password"
  }
}

Behavior

Rotates the recovery token — the old one is invalidated, a new one is returned in the response.
Bumps tokenVersion, which invalidates every existing session across all devices.
Does not sign the caller in — use /api/v1/auth/login afterward.
An unknown user and a wrong recovery key answer identically (constant-time comparison against a dummy hash for nonexistent accounts).

Rate Limits

Layer	Limit	Keyed by
Route limiter	8 per 15 min	IP
Per-identity backoff	5 free attempts, then doubling	Account + IP separately

The tighter limit (8 vs 20) reflects that there is no legitimate reason to call reset repeatedly — unlike login, a user resets once.

Errors

HTTP	Message	Cause
`400`	`All fields are required`	`login`, `recoveryKey`, or `password` missing/empty.
`400`	`Password must be at least 8 characters`	New password too short.
`401`	`That recovery key is not valid for this account`	Wrong key or unknown user — indistinguishable.
`401`	`A two-factor code is required`	Account has 2FA but no `twofa` was sent. Carries `twoFactorRequired: true`.
`401`	`Invalid two-factor code`	2FA code doesn’t match.
`403`	`Account is inactive or suspended`	Account status is not Active.
`429`	`Too many attempts — try again in Xs`	Per-identity lockout active.
`429`	`Too many reset attempts, try again later`	Route-level rate limit exceeded (8 per 15 min).
`500`	`Failed to reset the password`	Unhandled exception in the reset controller.