Saltar al contenido principal

Login de Usuario

Endpoint principal para autenticar usuarios en el sistema SwapBits usando email y contraseña con verificación inteligente basada en dispositivos confiables y ubicación geográfica.

Para información sobre headers HTTP requeridos, ver: Headers HTTP Globales

POST/auth/login

Autenticación principal que valida credenciales y determina el método de verificación requerido según el contexto de seguridad

📋 Parámetros

emailstringrequerido

Dirección de correo electrónico del usuario registrado

passwordstringrequerido

Contraseña del usuario

📤 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": false
  }
}
}

Nota sobre el campo token​

Importante: el campo token cambia según el flujo

Este endpoint devuelve el campo token con significados diferentes según el código:

  • Si code = 1001: token es el JWT de acceso.
  • Si code = 1010 o code = 4014: token es un sessionToken temporal para completar la verificación (email code o 2FA).

Tu cliente debe tomar decisiones por code, no solo por la presencia de token.

Flujo de Autenticación​

El sistema evalúa múltiples factores de seguridad:

1. Validación de Credenciales​

  • Verificación de formato de email
  • Validación de contraseña

2. Análisis de Contexto de Seguridad​

El sistema evalúa:

  • Dirección IP del cliente (incluye soporte para x-forwarded-for)
  • User-Agent del dispositivo
  • Ubicación geográfica (país/región)
  • Historial de sesiones/dispositivos confiables
  • Estado de 2FA
  • Flag bypassSecurity

3. Determinación del Flujo​

Según el contexto, el sistema puede:

  • Login directo (1001)
  • Verificación por email (1010)
  • Verificación 2FA (4014)
  • Bloqueos / autorización por email (4025 / 4026 / 4028)

Tipos de Respuesta​

Respuestas Exitosas​

Login Exitoso - Dispositivo Confiable

Código 1001 - Login exitoso.

{
  "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": false
    }
  }
}

Contextos comunes que generan esta respuesta:

  • Usuario con bypassSecurity: true
  • Dispositivo confiable (IP + User-Agent previamente autorizados)
  • IP previamente confiable en sesión actual
  • Misma región que último login con IP confiable

Verificación por Código de Email

Código 1010 - Se requiere verificación por código enviado al email.

{
  "code": 1010,
  "message": "Verification code sent successfully",
  "data": {
    "verificationType": "EMAIL_CODE",
    "token": "session-token-uuid"
  }
}

Nota: Esta respuesta es parte del flujo normal (no es error HTTP).

Verificación 2FA Requerida

Código 4014 - Se requiere código TOTP (2FA).

{
  "code": 4014,
  "message": "Two-factor authentication is required",
  "data": {
    "verificationType": "2FA_CODE",
    "token": "session-token-uuid"
  }
}

Nota: Esta respuesta es parte del flujo normal (no es error HTTP).

Errores de Autenticación​

Datos Faltantes o Inválidos

Código 4006 - Falta email/password o formato de email inválido.

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

Usuario No Encontrado

Código 4001 - El email no está registrado en el sistema.

{
  "code": 4001,
  "message": "User not found",
  "data": null
}

Credenciales Inválidas

Código 4007 - Contraseña incorrecta.

{
  "code": 4007,
  "message": "The provided password is incorrect",
  "data": null
}

Error de Autenticación

Código 4013 - Error de autenticación no clasificado (caso fallback).

{
  "code": 4013,
  "message": "Unauthorized",
  "data": null
}

Errores de Seguridad​

Dispositivo Previamente Revocado

Código 4025 - El dispositivo fue bloqueado manualmente por el usuario.

{
  "code": 4025,
  "message": "This device was previously revoked. Please check your email to authorize it again",
  "data": null
}

Nueva Ubicación Detectada

Código 4026 - Acceso desde nueva ubicación/región: se requiere autorización por email.

{
  "code": 4026,
  "message": "New location detected. Please check your email to authorize access",
  "data": null
}

Acción requerida:

  • Se envía un email con un enlace de autorización
  • El enlace expira en 10 minutos

Ubicación No Autorizada

Código 4028 - Hay una verificación pendiente no completada (bloquea nuevos intentos).

{
  "code": 4028,
  "message": "This location has not been authorized yet. Please check your email and authorize access first",
  "data": null
}

Nota: mientras exista una autorización pendiente no expirada, el backend puede rechazar nuevos intentos.

Próximos Pasos​

Después del Login

Dependiendo del code:

Si 1001

  • Guardar data.token como JWT de acceso
  • Usar data.user para estado de KYC y 2FA (twoFactorEnabled)

Si 1010

Si 4014

Si 4026 / 4025 / 4028

  • Informar al usuario que revise su email y complete autorización/desbloqueo
  • Reintentar login luego

Enlaces Relacionados​