Skip to content
/
Password Reset Verify
Last updated

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.

POSThttps://api.aitronos.com/v1/auth/password/reset/verify

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

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 CodeStatusDescription
VERIFICATION_CODE_INVALID422Code is invalid, expired, or already used
USER_NOT_FOUND404No user exists with the provided email
INVALID_PASSWORD_FORMAT422New password doesn't meet requirements
VERIFICATION_CODE_EXPIRED422Code 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
Previous page
Next page