Buscar en la documentación

Recuperar la contraseña

Código de 6 dígitos al correo, pase de un solo uso, contraseña nueva con el segundo factor si la cuenta lo tiene, y cierre de todas las sesiones.

Módulo auth2 min de lecturaVer en GitHub

La recuperación tiene tres pantallas: el correo, el código que llega al correo y la contraseña nueva. En ningún paso la respuesta revela si el correo está registrado: un correo desconocido recibe la misma respuesta y, más adelante, el mismo error que un código equivocado.

Diagrama5 carriles · 21 pasos · 5 salidas de error
SíNoSíNoSíNoSíNoSíNoSíNoEscribe su correoen /recuperar1Envía POST/auth/password/forgot2¿Menos de 3 en15 minutos?3Responde 429¿Es una cuentaactiva?4Guarda el códigopor 15 min y anulael anterior5Envía el código de6 dígitos6Responde 202siempre7Pide el código en/recuperar/codigo8Escribe el códigodel correo9Envía POST/auth/password/verify-code10¿Códigocorrecto,vigente y conintentos?11Responde 422Entrega un pase deun solo uso por 10min12Pide la contraseñanueva en/recuperar/nueva13Escribe lacontraseña nueva ysu confirmación14Envía POST/auth/password/reset15¿Cumple lapolítica decontraseñas?16Responde 422 porcampo¿El pase siguevigente?17Responde 422vencidoSi tiene MFA,¿segundofactorcorrecto?18Responde 422 conlo que quedaGuarda lacontraseña y cierratodas las sesiones19Aviso de contraseñacambiada20Vuelve al login conel aviso21
Los números coinciden con el paso a paso. En pantallas pequeñas el diagrama se desliza de lado.

Paso a paso

  1. PersonaEscribe su correo en /recuperar
  2. NavegadorEnvía POST /auth/password/forgot
  3. API¿Menos de 3 en 15 minutos?

    Límite password-forgot: 3 solicitudes cada 15 minutos por correo + IP.

  4. API¿Es una cuenta activa?
  5. Base de datosGuarda el código por 15 min y anula el anterior

    En password_reset_codes solo queda el HMAC-SHA256 del código, con la clave de la aplicación. Hay una sola solicitud vigente por persona.

  6. CorreoEnvía el código de 6 dígitos
  7. APIResponde 202 siempre

    La misma respuesta exista o no la cuenta.

  8. NavegadorPide el código en /recuperar/codigo

    El correo vive solo en memoria (useRecoveryStore). "Reenviar código" se habilita a los 60 segundos.

  9. PersonaEscribe el código del correo
  10. NavegadorEnvía POST /auth/password/verify-code

    Límite password-reset: 5 por minuto por correo + IP.

  11. API¿Código correcto, vigente y con intentos?

    Un correo desconocido, un código vencido o uno equivocado dan el mismo error. Al quinto fallo la solicitud se anula y queda el evento ResetCodeVoided.

  12. Base de datosEntrega un pase de un solo uso por 10 min

    El pase también se guarda como HMAC. La respuesta dice si la cuenta tiene MFA (mfa_required).

  13. NavegadorPide la contraseña nueva en /recuperar/nueva

    Muestra los requisitos. Si la cuenta tiene MFA, pide además el código de la aplicación o uno de recuperación.

  14. PersonaEscribe la contraseña nueva y su confirmación
  15. NavegadorEnvía POST /auth/password/reset
  16. API¿Cumple la política de contraseñas?

    De 12 a 128 caracteres, igual a la confirmación, sin patrones predecibles (repetida, en secuencia o con el correo) y que no esté en la lista local de 10.000 comunes ni en Have I Been Pwned, consultado por k-anonimato. Si Have I Been Pwned no responde en 3 s, sigue con la lista local.

  17. API¿El pase sigue vigente?
  18. APISi tiene MFA, ¿segundo factor correcto?

    Los fallos del segundo factor gastan los mismos 5 intentos de la solicitud. Usar un código de recuperación envía su aviso.

  19. Base de datosGuarda la contraseña y cierra todas las sesiones

    También levanta el bloqueo del login por intentos fallidos y avisa por el canal personal: las pantallas abiertas en otros equipos se cierran al instante.

  20. CorreoAviso de contraseña cambiada
  21. NavegadorVuelve al login con el aviso

    "Tu contraseña cambió y cerramos tus sesiones abiertas. Ingresa con la contraseña nueva."

Qué ve la persona en cada error

CódigoHTTPCuándoMensaje en pantalla
TOO_MANY_REQUESTS429Más de 3 solicitudes en 15 minutos, o más de 5 intentos de código en un minutoHiciste demasiados intentos seguidos. Espera {wait} y vuelve a intentarlo.
PASSWORD_RESET_CODE_INVALID422Código equivocado, vencido o anulado, o correo desconocidoEl código no es correcto o ya venció. Revisa el último correo que te enviamos o pide un código nuevo.
PASSWORD_RESET_EXPIRED422El pase venció, ya se usó o se agotaron los intentosPasó demasiado tiempo o el código ya se usó. Pide un código nuevo para cambiar tu contraseña.
PASSWORD_BREACHED422La contraseña es común o aparece en filtracionesEsta contraseña aparece en filtraciones conocidas o es de las más usadas. Elige una distinta, por ejemplo varias palabras que solo tú relaciones.
PASSWORD_REPETITIVE422Menos de 5 caracteres distintos o un bloque repetidoTu contraseña repite demasiado los mismos caracteres. Usa una frase o mezcla palabras distintas.
PASSWORD_SEQUENTIAL422Casi toda la contraseña es una secuenciaTu contraseña es casi toda una secuencia (como “abcd”, “1234” o “qwerty”). Usa palabras que no vayan seguidas.
PASSWORD_PERSONAL422Contiene el correo o el nombre de la aplicaciónTu contraseña contiene tu nombre, tu correo o el nombre de la aplicación. Elige palabras que no se relacionen con tu cuenta.
MFA_CODE_REQUIRED422La cuenta tiene MFA y no se envió ningún códigoTu cuenta tiene la verificación en dos pasos: escribe el código de tu aplicación o uno de tus códigos de recuperación.
MFA_CODE_INVALID422El código de la aplicación no correspondeEl código no es correcto. Escribe el que muestra ahora tu aplicación de autenticación.

Dónde está en el código