Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt

Use this file to discover all available pages before exploring further.

Password reset is a two-step flow. First, the user requests a reset email via /auth/forgot-password, which triggers delivery of a single-use reset link if the account exists. Second, the user submits the token from that link along with the desired new password to /auth/reset-password. The token is consumed immediately on use and cannot be reused. Both endpoints follow the same security posture as other auth endpoints: errors use application/problem+json and the first step applies anti-enumeration so that an attacker cannot determine whether a given email address has an account.

​
POST /auth/forgot-password

Initiates the password-reset flow by sending a reset email to the supplied address, if an ACTIVE account with that address exists. Authentication: None required

​
Request Body

​
email
string
required
The email address of the account for which a password reset is requested. Must not be blank. Maximum 254 characters.

​
Response — 202 Accepted

The server always returns 202 Accepted with the following body, regardless of whether the email address belongs to an existing account. 
{
  "message": "Si el email es válido, recibirás un correo con instrucciones para restablecer tu contraseña."
}

​
curl Example

curl -s -X POST http://localhost:8080/auth/forgot-password \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com"
  }'
Anti-enumeration protection: /auth/forgot-password always returns 202 Accepted with the same generic message body, whether or not an account with the supplied email address exists. This prevents an attacker from discovering registered email addresses by probing the endpoint.

​
POST /auth/reset-password

Completes the password-reset flow by accepting the single-use token from the reset email and the desired new password. Authentication: None required

​
Request Body

​
token
string
required
The password-reset token extracted from the link in the reset email. Must not be blank. This token is single-use and expires after 1 hour.
​
newPassword
string
required
The desired new password. Must not be blank. Password policy (minimum length, complexity) is enforced by the domain layer and returns a 400 if not met.

​
Response — 200 OK

{
  "message": "Tu contraseña ha sido restablecida. Ya puedes iniciar sesión con ella."
}

​
Error Responses

StatusCondition
400 Bad RequestThe token is invalid, has already been consumed, or has expired. Also returned if newPassword does not satisfy the password policy. Returns application/problem+json.
Example 400 response: 
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "El token de restablecimiento de contraseña es inválido o ha expirado.",
  "instance": "/auth/reset-password"
}

​
curl Example

curl -s -X POST http://localhost:8080/auth/reset-password \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "newPassword": "n3wS3cur3P@ss!"
  }'
Token TTL is 1 hour. If the reset link has expired before the user submits the form, they must start the flow again by calling /auth/forgot-password. The expired token will be rejected with a 400 Bad Request.
Single-use token: The reset token is invalidated immediately upon successful use. Attempting to reuse the same token — even with the correct new password — will return 400 Bad Request. This prevents replay attacks in which an attacker who intercepts the reset email can change the password a second time after the legitimate user has already consumed the token.

Build docs developers (and LLMs) love

Get started for freeTalk to us