Change Password

Change user password while authenticated. Requires current password verification.

Quick Navigation

• Endpoint
• Headers
• Request Body
• Parameters
• Validations
• Response
• Success (200)
• Error Codes
• Data Flow
• Features
• Security
• Example
• Related Endpoints

Endpoint

POST /api/v1/auth/change-password

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>
Content-Type	Yes	application/json

Request Body

{
  "current_password": "OldPassword123!",
  "new_password": "NewSecurePassword456!"
}

Parameters

Field	Type	Required	Description
current_password	string	Yes	Current password for verification
new_password	string	Yes	New password meeting strength requirements

Validations

• Current password verification
• Password strength validation (same as signup)
• New password must differ from current
• Authentication required

Response

Success (200)

{
  "success": true,
  "data": {
    "message": "Password changed successfully"
  },
  "message": "Password changed successfully"
}

Error Codes

Status	Code	Description
400	INVALID_CURRENT_PASSWORD	Current password is incorrect
400	CHANGE_PASSWORD_FAILED	Password change failed
401	UNAUTHORIZED	Invalid or missing token
401	USER_NOT_FOUND	User not found
422	VALIDATION_ERROR	Request validation failed

Data Flow

1. Authentication

   • Verify access token
   • Get current user

2. Current Password Verification

   • Hash current_password
   • Compare with stored password hash
   • Return error if mismatch

3. Password Validation

   • Validate new password strength
   • Check password requirements
   • Verify new password differs from current

4. Password Update

   • Hash new password with bcrypt
   • Update user.password_hash
   • Clear password reset tokens

5. Session Revocation

   • Revoke all existing refresh tokens
   • Invalidate all active sessions
   • Force re-authentication on all devices

6. Email Notification

   • Send password change confirmation email
   • Queue email via email service

7. Audit Logging

   • Log password change event
   • Record IP address

Features

• Validates current password
• Updates password with new hash
• Revokes all existing sessions (security measure)
• Sends confirmation email
• Audit logging
• Forces re-authentication on all devices

Security

• Requires valid authentication
• Validates current password before change
• Revokes all sessions after password change
• Sends confirmation email
• Prevents reuse of old password (optional)

Example

curl -X POST https://api.rivergen.com/api/v1/auth/change-password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPassword123!",
    "new_password": "NewSecurePassword456!"
  }'

Related Endpoints

• Reset Password - Reset password without current password
• Logout All - Explicitly logout all sessions