Password Reset

This endpoint allows you to reset the password for your account by providing your email and current password along with the new password.

Overview

The password reset endpoint provides a secure method for users to change their account password. After authenticating with their email and current password, the system validates the new password against security requirements, updates the credentials in the database, and returns a confirmation of the successful change. This streamlined process ensures account security while offering a straightforward user experience.

Endpoint Flow

The following diagram illustrates the password reset process:

Endpoint Details

Method: POST
URL: /api/institutions/v1/auth/password/reset Purpose: Reset a user's password for their Presto account

Request Specification

Request Parameters

Parameter	Type	Required	Description
email	string	Yes	The email address associated with your Presto account
current_password	string	Yes	The current password for your Presto account
new_password	string	Yes	The new password you wish to set for your account

Password Requirements

Passwords must be at least 8 characters long and include a combination of uppercase letters, lowercase letters, numbers, and special characters.

Example Request

// Headers:
// Content-Type: application/json

{
  "email": "institution@example.com",
  "current_password": "your-current-password",
  "new_password": "your-new-secure-password"
}

Response Specification

Success Response

200 OK

A successful response confirms that the password has been reset.

{
  "message": "Password has been successfully reset",
  "data": {
    "updated_at": "2025-05-25T18:54:00Z"
  }
}

Response Fields

Field	Type	Description
updated_at	string	The timestamp when the password was reset

Error Responses

401 Unauthorized - Authentication issues

{
  "message": "Invalid email or current password"
}

422 Unprocessable Content - Input validation issues

{
  "message": "The new password field must be at least 8 characters.",
  "errors": {
    "new_password": [
      "The new password field must be at least 8 characters.",
      "The new password must contain at least one uppercase letter.",
      "The new password must contain at least one lowercase letter.",
      "The new password must contain at least one number.",
      "The new password must contain at least one special character."
    ]
  }
}

422 Unprocessable Content - Missing required fields

{
  "message": "The email field is required. The current password field is required.",
  "errors": {
    "email": [
      "The email field is required."
    ],
    "current_password": [
      "The current password field is required."
    ],
    "new_password": [
      "The new password field is required."
    ]
  }
}

Error Handling

Common Errors

Error Type	Possible Cause	Resolution
Authentication Error (401)	Incorrect email or current password	Verify your email and current password are correct
Validation Error (422)	New password doesn't meet security requirements	Ensure your new password meets all security requirements (check the 'errors' object in the response)
Validation Error (422)	Missing required fields	Check that all required fields (email, current_password, new_password) are included in your request

Implementation Tips

Best Practices

• Always verify the user's identity before allowing a password reset
• Implement client-side validation for password requirements
• Use HTTPS for all authentication-related endpoints
• Prompt users to log in again after password changes
• Notify users via email when their password has been changed
• Store new authentication tokens securely after password changes
• Set reasonable expiration dates for any new tokens issued after password reset