Saltar al contenido principal

Solicitar Cambio de Contraseña

Inicia una sesión temporal de validación para permitir el cambio de contraseña de forma segura.

🔐 Autenticación Requerida

Este endpoint requiere que el usuario esté autenticado.

Debe enviarse un JWT válido en el header:

Authorization: Bearer <access_token>

Endpoint​

POST/auth/account/password/request

Inicia una sesión de cambio de contraseña y devuelve un token de validación temporal

📋 Parámetros

Authorizationstringrequerido

JWT en formato Bearer

📤 Respuesta

{
"code": 1010,
"message": "Verification code sent successfully.",
"data": {
  "requiresVerification": true,
  "verificationType": "PASSWORD_ONLY",
  "message": "Please provide current password and new password",
  "fields": ["currentPassword", "newPassword"],
  "validationToken": "uuid-validation-token"
}
}

¿Para qué sirve este endpoint?​

Este endpoint NO cambia la contraseña directamente.

Su propósito es:

  • Crear una sesión temporal segura
  • Determinar si el usuario tiene 2FA habilitado
  • Indicar al frontend qué datos debe solicitar
  • Proveer un validationToken que se usará en el siguiente paso

Flujo para Frontend​

🧭 Flujo de Cambio de Contraseña

Paso 1 – Request (este endpoint)​

  1. El frontend llama a /auth/account/password/request
  2. Recibe un validationToken
  3. Recibe la lista de campos requeridos (fields)
  4. Guarda temporalmente el validationToken

Paso 2 – Execute​

  • El frontend envía el validationToken
  • Incluye los campos solicitados
  • Se ejecuta el cambio de contraseña

Tipos de Respuesta​

✅ Usuario SIN 2FA​

Solo Contraseñas

El usuario solo debe ingresar su contraseña actual y la nueva.

{
  "code": 1010,
  "data": {
    "verificationType": "PASSWORD_ONLY",
    "fields": ["currentPassword", "newPassword"],
    "validationToken": "uuid"
  }
}

🔐 Usuario CON 2FA​

Requiere 2FA

El usuario debe ingresar contraseña actual, nueva contraseña y código 2FA.

{
  "code": 1010,
  "data": {
    "verificationType": "2FA_REQUIRED",
    "fields": ["currentPassword", "newPassword", "twoFACode"],
    "validationToken": "uuid"
  }
}

Uso Correcto en Frontend​

Buenas Prácticas

  • Guardar validationToken solo en memoria o sessionStorage
  • No persistirlo en localStorage
  • Mostrar dinámicamente los campos indicados en fields
  • Continuar el flujo antes de 5 minutos
  • Si expira, volver a llamar a este endpoint

Ejemplo de Uso (Frontend)​

const requestPasswordChange = async (accessToken) => {
  const res = await fetch(
    'https://api.swapbits.co/auth/account/password/request',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${accessToken}`
      }
    }
  );

  const result = await res.json();

  if (result.code === 1010) {
    sessionStorage.setItem(
      'passwordChangeToken',
      result.data.validationToken
    );

    return result.data;
  }

  throw new Error(result.message);
};

Qué hacer si falla​

SituaciónAcción
Token expiradoRepetir el request
Usuario cierra sesiónDescartar token
Error inesperadoMostrar mensaje genérico

Enlaces Relacionados​