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.

Auth Service provides a two-step password reset flow: the user requests a reset email, receives a link containing a single-use token, and submits that token along with their new password. The entire flow is designed with anti-enumeration principles — the request endpoint always returns the same response regardless of whether the email belongs to a real account, preventing attackers from probing the user database.
1

Request a password reset email

The user submits their email address. Auth Service queues a reset email if — and only if — an active account exists for that address. The HTTP response is always 202 Accepted with a generic message.
curl -X POST https://your-auth-service/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
Response — 202 Accepted
{
  "message": "Si el email es válido, recibirás un correo con instrucciones para restablecer tu contraseña."
}
This endpoint intentionally returns an identical 202 Accepted response whether or not the email address corresponds to a registered account. This is an anti-enumeration control: an attacker cannot use this endpoint to determine whether a given email exists in the system. Never modify this behavior to return a 404 for unknown emails.
2

User receives the reset email

If the account exists, Auth Service sends an email containing a password reset link. The link includes a single-use token as a URL parameter, constructed using the APP_BASE_URL environment variable:
{APP_BASE_URL}/auth/reset-password?token=<reset-token>
Your frontend should be configured to intercept this URL, extract the token parameter from the query string, and present a “set new password” form to the user.Reset token properties:
PropertyValue
FormatCryptographically random opaque string
StorageSHA-256 hash stored in the database (raw value never persisted)
TTL1 hour from generation
ReuseSingle-use; consumed immediately on successful reset
3

Submit the new password

Once the user enters their new password, your frontend posts the token and the new password to /auth/reset-password.
curl -X POST https://your-auth-service/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<reset-token-from-email>",
    "newPassword": "n3wS3cur3P@ss"
  }'
Response — 200 OK
{
  "message": "Tu contraseña ha sido restablecida. Ya puedes iniciar sesión con ella."
}
Unlike /auth/forgot-password, this endpoint does return a distinguishable error response when the token is invalid. The caller already possesses the token, so there is no enumeration risk in revealing that it did not work.Error cases that return 400 Bad Request:
  • The token does not exist in the database
  • The token has expired (TTL of 1 hour)
  • The token has already been consumed (already used for a previous reset)
All three cases return a 400 Bad Request with an application/problem+json body.

​
Effect on active sessions

A successful password reset revokes all existing refresh tokens for the account. Any device or session that holds a refresh token for this user will be logged out and must re-authenticate with the new password. This prevents a scenario where an attacker who obtained a refresh token before the reset continues to maintain access after the user has secured their account.

​
Configuration

Environment variableDescription
APP_BASE_URLBase URL of the Auth Service instance. Used to construct the reset link embedded in the password reset email. Example: https://auth.example.com.
Ensure APP_BASE_URL is set correctly for each environment. In local development the default is http://localhost:8080; outgoing emails are captured by MailHog at http://localhost:8025.

Build docs developers (and LLMs) love

Get started for freeTalk to us