Skip to main content
The password reset flow consists of three endpoints that work together to securely reset a user’s password:
  1. Request password reset - Initiates the reset process
  2. Validate reset token - Verifies the token is valid
  3. Complete password reset - Sets the new password
Source: PasswordResetController.java

​
POST /auth/forgot-password

Initiates the password reset process by sending a reset link to the user’s registered email address. Authentication: None required (public endpoint) Source: PasswordResetController.java:26

​
Request

​
username
string
required
Username or email address of the account to reset. The system will send a password reset link if this account exists.Note: For security reasons, the response is always successful regardless of whether the username exists.

​
Response

​
success
boolean
Always returns true
​
message
string
Confirmation message: “Si el correo está registrado, recibirás en breve el enlace de recuperación. Puede tardar un momento.”

​
Example

curl -X POST https://api.integra.example.com/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jdoe"
  }'

​
Success Response

{
  "success": true,
  "message": "Si el correo está registrado, recibirás en breve el enlace de recuperación. Puede tardar un momento."
}
The response is intentionally vague to prevent username enumeration attacks. An email is only sent if the username exists in the system.

​
POST /auth/validate-reset-token

Validates that a password reset token is valid and not expired. Use this endpoint to verify a token before showing the password reset form. Authentication: None required (public endpoint) Source: PasswordResetController.java:36

​
Request

​
token
string
required
The password reset token received via email. This token is typically extracted from the reset link URL.

​
Response

Success (200 OK):
​
valid
boolean
Returns true if the token is valid and not expired
Error (400 Bad Request):
​
valid
boolean
Returns false if the token is invalid or expired
​
message
string
Error message explaining why the token is invalid

​
Example

curl -X POST https://api.integra.example.com/auth/validate-reset-token \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'

​
Success Response

{
  "valid": true
}

​
Error Response

{
  "valid": false,
  "message": "Token inválido o expirado"
}

​
POST /auth/reset-password

Completes the password reset process by setting a new password for the user account. Authentication: None required (token-based verification) Source: PasswordResetController.java:47

​
Request

​
token
string
required
The valid password reset token received via email
​
newPassword
string
required
The new password to set for the user account. Should meet the application’s password complexity requirements.

​
Response

Success (200 OK):
​
message
string
Success message: “Contraseña actualizada correctamente.”
Error (400 Bad Request):
​
error
string
Error message explaining why the password reset failed (e.g., invalid token, expired token, weak password)

​
Example

curl -X POST https://api.integra.example.com/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "newPassword": "NewSecureP@ssw0rd!"
  }'

​
Success Response

{
  "message": "Contraseña actualizada correctamente."
}

​
Error Responses

{
  "error": "Token inválido o expirado"
}

{
  "error": "La contraseña no cumple con los requisitos de seguridad"
}

​
Complete Password Reset Flow

Here’s how the three endpoints work together:
1

User requests password reset

User enters their username/email on the forgot password page. Your application calls POST /auth/forgot-password.
2

User receives email

If the account exists, the user receives an email with a password reset link containing a token:
https://yourapp.com/reset-password?token=a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
3

Validate the token

When the user clicks the link, your application extracts the token from the URL and calls POST /auth/validate-reset-token to verify it’s valid before showing the password reset form.
4

User sets new password

User enters their new password. Your application calls POST /auth/reset-password with the token and new password.
5

Redirect to login

After successful password reset, redirect the user to the login page to sign in with their new credentials.
Reset tokens are single-use and expire after a set period (typically 1 hour). Once a password is successfully reset, the token is invalidated and cannot be reused.
Always validate the token before showing the password reset form to provide immediate feedback if the link has expired or is invalid.

Build docs developers (and LLMs) love

Get started for freeTalk to us