> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frostauth.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Password Reset

> Reset a Frost Auth console operator password using a recovery token.

# Password Reset

```http theme={null}
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

```json theme={null}
{
  "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

```text 200 Success theme={null}
{
  "success": true,
  "response": {
    "data": {
      "reset": true,
      "recoveryKey": "frostauth-rt-NEW_ROTATED_KEY...",
      "sessionsRevoked": true
    }
  }
}
```

```text 400 Bad Request theme={null}
{
  "error": true,
  "response": {
    "code": 400,
    "message": "All fields are required"
  }
}
```

```text 401 Unauthorized theme={null}
{
  "error": true,
  "response": {
    "code": 401,
    "message": "That recovery key is not valid for this account"
  }
}
```

```text 403 Forbidden theme={null}
{
  "error": true,
  "response": {
    "code": 403,
    "message": "Account is inactive or suspended"
  }
}
```

```text 429 Rate Limited theme={null}
{
  "error": true,
  "response": {
    "code": 429,
    "message": "Too many reset attempts, try again later"
  }
}
```

```text 500 Server Error theme={null}
{
  "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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.