Skip to main content
The password reset process consists of two steps: requesting a reset link and using the token to set a new password.

​
Step 1: Request Password Reset

Forgot Password

Send a password reset link to the user’s email address.
POST /api/auth/forgot-password

​
Request Parameters

​
email
string
required
Email address of the account to reset. Case-insensitive.

​
Response

​
success
boolean
Indicates if the request was successful
​
message
string
Generic message to prevent email enumeration: “If your email is registered, you will receive a password reset link”
​
data
object
Contains the same message as above

​
Example Request

curl -X POST https://api.millenniumpotters.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

​
Example Response

{
  "success": true,
  "message": "If your email is registered, you will receive a password reset link",
  "data": {
    "message": "If your email is registered, you will receive a password reset link"
  }
}

​
Reset Email Details

  • Reset token is valid for 1 hour
  • Email contains a link in the format: {FRONTEND_URL}/reset-password?token=<reset_token>
  • Tokens are securely hashed using SHA-256 before storage
  • The same success message is returned whether or not the email exists (security best practice)

​
Step 2: Reset Password

Reset Password

Use the reset token from the email to set a new password.

​
Set New Password

POST /api/auth/reset-password

​
Request Parameters

​
token
string
required
The reset token received in the email (extracted from the URL query parameter)
​
newPassword
string
required
The new password. Must meet security requirements:
  • Minimum 8 characters
  • At least one uppercase letter
  • At least one lowercase letter
  • At least one number

​
Response

​
success
boolean
Indicates if the password reset was successful
​
message
string
Response message (“Password reset successful”)
​
data
object
Contains the success message

​
Example Request

curl -X POST https://api.millenniumpotters.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "newPassword": "NewSecurePass123"
  }'

​
Example Response

{
  "success": true,
  "message": "Password reset successful",
  "data": {
    "message": "Password reset successful"
  }
}

​
After Password Reset

  • All existing sessions are automatically revoked
  • User must log in again with the new password
  • A confirmation email is sent to the user
  • The reset token is invalidated and cannot be reused

​
Error Responses

Returned when attempting to reset password for an inactive account.
{
  "success": false,
  "message": "Account is inactive"
}
Returned when the email format is invalid.
{
  "success": false,
  "message": "Invalid email address"
}
Returned when the reset token is invalid, expired, or already used.
{
  "success": false,
  "message": "Token is invalid or has expired"
}
Returned when the new password doesn’t meet security requirements.
{
  "success": false,
  "message": "Password must be at least 8 characters"
}

​
Security Features

  • Reset tokens are hashed using SHA-256 before storage
  • Tokens expire after 1 hour
  • Generic success messages prevent email enumeration attacks
  • All sessions are revoked after password reset
  • Password change notifications are sent to the user’s email
  • Failed reset attempts are logged

Build docs developers (and LLMs) love

Get started for freeTalk to us