Saltar al contenido principal

Verificación 2FA en Login

Endpoint para completar el proceso de autenticación mediante código TOTP (2FA) generado por una app autenticadora.

POST/auth/login/2fa

Verifica el código TOTP y completa el login para usuarios con 2FA habilitado

📋 Parámetros

codestringrequerido

Código de 6 dígitos generado por la app autenticadora (TOTP)

tokenstringrequerido

Session token temporal obtenido desde /auth/login cuando responde code 4014

📤 Respuesta

{
"code": 1001,
"message": "Login successful",
"data": {
  "token": "jwt-access-token",
  "user": {
    "id": "user-id",
    "email": "usuario@ejemplo.com",
    "kyc": {
      "status": "None",
      "isVerified": false,
      "kycId": null
    },
    "twoFactorEnabled": true
  }
}
}

Contexto de Uso​

Este endpoint se utiliza cuando:

  1. El usuario hace login en /auth/login
  2. La API responde con code = 4014 y:
    • verificationType: "2FA_CODE"
    • token (sessionToken temporal)
  3. El cliente solicita el código TOTP al usuario
  4. Se llama a /auth/login/2fa con:
    • code (6 dígitos)
    • token (sessionToken temporal)

Validación de Entrada​

Formato del Código 2FA

  • Debe tener exactamente 6 dígitos (0-9)
  • Ejemplo válido: 123456

Token Temporal de Sesión

  • Es el token retornado por /auth/login cuando code = 4014
  • Se valida contra el valor almacenado en Redis bajo sessionToken:{token}
  • Si no existe o es inválido, el servidor responde con 4015

Tipos de Respuesta​

Autenticación 2FA Exitosa

Código 1001 - Código TOTP válido. Se emite el JWT final y se retorna el usuario.

{
  "code": 1001,
  "message": "Login successful",
  "data": {
    "token": "jwt-access-token",
    "user": {
      "id": "user-id",
      "email": "usuario@ejemplo.com",
      "kyc": {
        "status": "None",
        "isVerified": false,
        "kycId": null
      },
      "twoFactorEnabled": true
    }
  }
}

Qué sucede en éxito:

  • Se elimina el sessionToken de Redis (uso único)
  • Se registra el login exitoso en auditoría/actividad

Código 2FA Inválido

Código 4005 - El código TOTP es incorrecto.

{
  "code": 4005,
  "message": "Invalid verification code.",
  "data": null
}

HTTP: 401 Unauthorized

Token de Sesión Inválido

Código 4015 - El token temporal no existe o no es válido.

{
  "code": 4015,
  "message": "Invalid or expired token",
  "data": null
}

Acción sugerida: el usuario debe iniciar sesión nuevamente en /auth/login.

Datos Faltantes o Inválidos

Código 4006 - Faltan datos o el formato es inválido.

{
  "code": 4006,
  "message": "Missing required data",
  "data": null
}

HTTP: 400 Bad Request

Próximos Pasos​

Después de Verificar 2FA

  • Guardar data.token como JWT de acceso
  • Usar data.user para estado de KYC y 2FA
  • El sessionToken temporal ya no debe reutilizarse (es de uso único)

Enlaces Relacionados​