> ## 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.

# Reset Recovery Key

> Generate a new recovery token for a Frost Auth console account.

# Reset Recovery Key

```http theme={null}
POST /api/v1/auth/recovery-key
Content-Type: application/json
```

Issues a new recovery token, replacing the previous one. Requires an active `session_token` and, when 2FA is enabled, a valid TOTP code.

## Request

```json theme={null}
{
  "password": "••••••••",
  "code": "000000"
}
```

## Parameters

| Field | Required | Description |
| - | - | - |
| `password` | Yes | Current account password. |
| `code` | Conditional | Valid TOTP code from the authenticator. Required when 2FA is enabled. Recovery codes are explicitly refused here — a recovery code must not be spendable to mint a fresh master credential. |

## Responses

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

```text 400 Bad Request theme={null}
{
  "error": true,
  "response": {
    "code": 400,
    "message": "Use a code from your authenticator, not a recovery code"
  }
}
```

```text 401 Unauthorized theme={null}
{
  "error": true,
  "response": {
    "code": 401,
    "message": "Not authenticated"
  }
}
```

```text 404 Not Found theme={null}
{
  "error": true,
  "response": {
    "code": 404,
    "message": "User doesn't exist"
  }
}
```

```text 429 Rate Limited theme={null}
{
  "error": true,
  "response": {
    "code": 429,
    "message": "Too many requests"
  }
}
```

```text 500 Server Error theme={null}
{
  "error": true,
  "response": {
    "code": 500,
    "message": "Failed to reissue the recovery key"
  }
}
```

## Behavior

* The old recovery token is invalidated immediately.
* The new token is returned exactly once — store it securely.
* Does **not** bump `tokenVersion` — other sessions remain valid.

## Rate Limits

| Layer | Limit | Keyed by |
| - | - | - |
| 2FA limiter | 10 per 1 min | Account |
| Per-identity backoff | Applies to password/code failures | Account |

## Errors

| HTTP | Message | Cause |
| - | - | - |
| `400` | `Use a code from your authenticator, not a recovery code` | A recovery code was supplied instead of TOTP. |
| `401` | `Not authenticated` | No valid session cookie. |
| `401` | `Your password is incorrect` | Password verification failed. |
| `401` | `Invalid two-factor code` | TOTP code doesn't match. |
| `404` | `User doesn't exist` | Session's user ID not found in database. |
| `429` | `Too many requests` | 10 per minute per account. |
| `500` | `Failed to reissue the recovery key` | Unhandled exception. |


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