Saltar al contenido principal

Configurar 2FA

Endpoint para generar el secreto y el código QR necesarios para iniciar la configuración de autenticación de dos factores (2FA) en la cuenta del usuario.

🔐 Seguridad Mejorada con 2FA

La autenticación de dos factores añade una capa adicional de seguridad.
Tras configurarla, además de tu contraseña necesitarás un código temporal (TOTP) generado por una app autenticadora.

POST/auth/account/2fa/setup

Genera secreto y código QR para iniciar la configuración de 2FA

📤 Respuesta

{
"code": 2003,
"message": "Two-factor authentication generated successfully.",
"data": {
  "status": "pending",
  "base32": "JBSWY3DPEHPK3PXP",
  "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "token": "setup-token"
}
}

Autenticación​

JWT Requerido

Este endpoint requiere un JWT válido:

Authorization: Bearer <access_token>

Flujo recomendado​

1) Generar secreto y QR (este endpoint)​

  • Obtendrás qrcode para que el usuario lo escanee con su app autenticadora.
  • Guarda temporalmente el token devuelto para el siguiente paso.

2) Verificar y activar 2FA​

  • Usa el endpoint de verificación (ej: /auth/account/2fa/verify) enviando:

    • token (del setup)
    • code (TOTP de 6 dígitos de la app)

Respuesta exitosa​

Secreto generado

Código 2003 - Se generó el secreto y el QR.

{
  "code": 2003,
  "message": "Two-factor authentication generated successfully.",
  "data": {
    "status": "pending",
    "base32": "JBSWY3DPEHPK3PXP",
    "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "token": "setup-token"
  }
}

Campos:

  • base32: secreto en base32 (para apps TOTP)
  • qrcode: QR en base64 para mostrar en UI
  • token: token temporal para completar la configuración en el paso de verificación
  • status: "pending"

Validez del token​

⏱️ Expiración

  • El token de configuración expira en 1 minuto.
  • Si expira, debes llamar nuevamente a este endpoint para generar uno nuevo.

Errores​

No autenticado

Si el JWT es inválido o no se envía, el servidor responderá con 401 Unauthorized.

Apps autenticadoras compatibles​

📱 Apps recomendadas

  • Google Authenticator
  • Authy
  • Microsoft Authenticator
  • FreeOTP

Todas soportan TOTP (RFC 6238).

Ejemplo JavaScript/TypeScript​

async function setup2FA(accessToken) {
  const res = await fetch('https://api.swapbits.co/auth/account/2fa/setup', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  });

  const result = await res.json();

  if (result.code === 2003) {
    // Mostrar QR en UI
    // result.data.qrcode
    // Guardar token para verify
    // result.data.token
    return result.data;
  }

  return result;
}

cURL​

curl -X POST 'https://api.swapbits.co/auth/account/2fa/setup' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json'

Enlaces Relacionados​