Saltar al contenido principal

Solicitar Restablecimiento de Contraseña

Envía un enlace de restablecimiento de contraseña a la dirección de email del usuario. Usa esto cuando los usuarios olvidan su contraseña.

Endpoint​

POST /api/v1/auth/password-reset

Autenticación​

No se requiere autenticación (endpoint público).

Request​

Content-Type​

application/json

Request Body​

CampoTipoRequeridoDescripción
emailstringSíDirección de email para enviar enlace de restablecimiento

Ejemplo de Request​

{
  "email": "juan@ejemplo.com"
}

Response​

Response Exitoso (200 OK)​

{
  "message": "Si el email existe, se ha enviado un enlace de restablecimiento de contraseña",
  "success": true
}
Nota de Seguridad

El endpoint siempre devuelve éxito, incluso si el email no existe. Esto previene que atacantes descubran qué emails están registrados.

Ejemplos​

curl -X POST https://api.callcov.com/api/v1/auth/password-reset \
-H "Content-Type: application/json" \
-d '{
  "email": "juan@ejemplo.com"
}'

Flujo de Restablecimiento de Contraseña​

  1. Usuario solicita restablecimiento → Este endpoint
  2. Backend envía email → Email con enlace de restablecimiento y token
  3. Usuario hace clic en enlace → Redirigido al frontend con token
  4. Usuario ingresa nueva contraseña → Frontend llama /auth/password-reset/confirm
  5. Contraseña actualizada → Usuario puede iniciar sesión con nueva contraseña

Contenido del Email​

Los usuarios reciben un email que contiene:

  • Enlace de restablecimiento de contraseña con token
  • El enlace expira en 15 minutos
  • El token es de un solo uso

Ejemplo de email:

Asunto: Restablece tu contraseña de CallCov

Haz clic en el enlace de abajo para restablecer tu contraseña:
https://app.callcov.com/reset-password-confirmation?token=abc123...

Este enlace expira en 15 minutos.

Si no solicitaste esto, puedes ignorar este email de forma segura.

Integración con Frontend​

Formulario típico de "Olvidé mi Contraseña":

async function handleForgotPassword(email) {
  try {
    const response = await fetch('https://api.callcov.com/api/v1/auth/password-reset', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email })
    });

    if (response.ok) {
      // Mostrar mensaje de éxito
      alert('Si tu email está registrado, recibirás un enlace de restablecimiento de contraseña.');
    }
  } catch (error) {
    console.error('Error:', error);
    alert('Algo salió mal. Por favor intenta de nuevo.');
  }
}

Limitación de Tasa​

Para prevenir abuso:

  • Máximo 3 requests por email por hora
  • Máximo 10 requests por IP por hora

Comportamiento de Seguridad​

Cuando este endpoint es llamado:

  1. Invalida todos los tokens de restablecimiento anteriores para este usuario
  2. Genera nuevo token de restablecimiento (expira en 15 minutos)
  3. Envía email de restablecimiento
  4. Siempre devuelve éxito (incluso si el email no existe)

Consideraciones de Seguridad​

  • Protección contra enumeración de emails: Siempre devuelve éxito
  • Invalidación de tokens: Los tokens de restablecimiento anteriores se invalidan
  • Tiempo limitado: Los tokens expiran en 15 minutos
  • Un solo uso: Los tokens solo pueden usarse una vez
  • Limitación de tasa: Previene bombardeo de emails

Pruebas en Desarrollo​

En modo de desarrollo, los emails de restablecimiento se envían a MailHog (http://localhost:8025).

Problemas Comunes​

Email No Recibido​

Razones posibles:

  1. Email en carpeta de spam
  2. Dirección de email incorrecta
  3. Problema temporal del servicio de email

Solución: Esperar unos minutos, revisar spam, o intentar reenviar.

Límite de Tasa Excedido​

{
  "detail": "Demasiadas solicitudes de restablecimiento de contraseña. Por favor intenta de nuevo más tarde."
}

Solución: Esperar una hora antes de intentar de nuevo.

Ejemplo de Formulario de Restablecimiento Completo​

function ForgotPasswordForm() {
  const [email, setEmail] = useState('');
  const [sent, setSent] = useState(false);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);

    try {
      await fetch('https://api.callcov.com/api/v1/auth/password-reset', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email })
      });

      setSent(true);
    } catch (error) {
      alert('Algo salió mal. Por favor intenta de nuevo.');
    } finally {
      setLoading(false);
    }
  };

  if (sent) {
    return (
      <div className="success-message">
        <h2>Revisa tu email</h2>
        <p>
          Si tu email está registrado, recibirás un enlace de restablecimiento de contraseña
          pronto.
        </p>
        <p>
          ¿No lo recibiste? Revisa tu carpeta de spam o intenta de nuevo en unos
          minutos.
        </p>
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit}>
      <h2>¿Olvidaste tu Contraseña?</h2>
      <p>Ingresa tu email y te enviaremos un enlace de restablecimiento.</p>

      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="tu@email.com"
        required
      />

      <button type="submit" disabled={loading}>
        {loading ? 'Enviando...' : 'Enviar Enlace de Restablecimiento'}
      </button>

      <a href="/login">Volver al Login</a>
    </form>
  );
}

Relacionado​