# Password Reset Verify

**POST** `/v1/auth/password/reset/verify` - Verify the 4-digit code from the password reset email and set a new password. This completes the password reset flow and revokes all existing user sessions.

Validates the 4-digit verification code sent via email and updates the user's password. All existing refresh tokens are revoked, forcing re-authentication on all devices. The code expires after 5 minutes and is single-use only.

#### Request Body

**`email`** string required

User's email address. Must match the email used in the password reset request.

**`verification_code`** integer required

4-digit verification code (1000-9999) received via email. Code expires after 5 minutes.

**`new_password`** string required

New password. Must meet complexity requirements: minimum 8 characters and at least one special character.

## Returns

A Password Reset Verify Response object containing confirmation of successful password reset.

**`success`** boolean

Indicates if the password was reset successfully. Always `true` for successful resets.

**`message`** string

Success message confirming the password reset.

## Complete Password Reset Flow

### Step 1: Request Password Reset

User enters their email on the "Forgot Password" page.


```
POST /v1/auth/password/reset
{ "email": "user@example.com" }
```

### Step 2: User Receives Email

Email contains:

- **4-digit verification code** (e.g., 1234)
- **Password reset link** with pre-filled email and code
- **Username** for reference
- **Expiry time** (5 minutes)


Example link: `https://freddy-hub.aitronos.com/auth/reset-password?email=user@example.com&code=1234`

### Step 3: User Clicks Link or Enters Code

User is taken to the password reset page where:

- Email is pre-filled from URL parameter
- Code is pre-filled from URL parameter (or user enters manually)
- User enters their new password
- User confirms the new password


### Step 4: Submit Password Reset


```
POST /v1/auth/password/reset/verify
{
  "email": "user@example.com",
  "verification_code": 1234,
  "new_password": "NewSecurePassword123!"
}
```

### Step 5: Success

- Password is updated
- All existing sessions are revoked
- User is redirected to login page
- User logs in with new password


## Security Features

- **Time-limited codes**: Verification codes expire after 5 minutes
- **One-time use**: Codes are marked as used after successful verification
- **Password validation**: New password must meet strength requirements
- **Session revocation**: All existing refresh tokens are revoked on success
- **Rate limiting**: Prevents brute force attacks on verification codes
- **Automatic cleanup**: Expired codes are automatically cleaned up


## Password Requirements

- **Minimum length**: 8 characters
- **Special character**: At least one special character required
- **Not common**: Password cannot be in the common weak passwords list
- **Maximum length**: 72 characters (bcrypt limit)


## Error Handling

| Error Code | Status | Description |
|  --- | --- | --- |
| `VERIFICATION_CODE_INVALID` | 422 | Code is invalid, expired, or already used |
| `USER_NOT_FOUND` | 404 | No user exists with the provided email |
| `INVALID_PASSWORD_FORMAT` | 422 | New password doesn't meet requirements |
| `VERIFICATION_CODE_EXPIRED` | 422 | Code has expired (>5 minutes old) |


## Best Practices

1. **Pre-fill from URL**: Extract email and code from URL parameters when user clicks the email link
2. **Show expiry timer**: Display countdown showing when the code expires
3. **Validate password client-side**: Check password requirements before submitting
4. **Handle errors gracefully**: Show user-friendly error messages
5. **Redirect to login**: After successful reset, redirect to login page
6. **Clear sensitive data**: Don't store the verification code in browser storage
7. **Request new code**: Provide option to request a new code if expired