Saltar al contenido principal

Verificar PIN de seguridad

Endpoint: POST /auth/pin/verify

Permite verificar el PIN de seguridad y crear una sesión aprobada que permite acceso a operaciones sensibles sin necesidad de re-verificar el PIN durante un tiempo determinado.

🔐 Requiere autenticación JWT​

Debes enviar un token JWT válido en el header:

Authorization: Bearer <accessToken>

📝 Cuerpo de la solicitud​

{
  "pin": "123456"
}
  • pin: PIN de seguridad de 6 dígitos numéricos

📋 Respuestas​

✅ 200 OK​

  • PIN verificado correctamente

    {
      "code": 1001,
      "message": "PIN verified successfully. Session approved.",
      "data": {
        "verified": true,
        "verifiedAt": "2025-01-20T14:45:00.000Z",
        "sessionApproved": true,
        "sessionId": "jwt-jti-uuid",
        "expiresAt": "2025-01-21T14:45:00.000Z",
        "inactivityTimeout": "5 minutes"
      }
    }

❌ 400 Bad Request​

  • PIN incorrecto con intentos restantes

    {
      "code": 4007,
      "message": "Invalid PIN. 3 attempts remaining.",
      "details": {
        "remainingAttempts": 3,
        "totalAttempts": 5
      }
    }

  • PIN no configurado

    {
      "code": 4006,
      "message": "PIN not configured for this user"
    }

  • Formato de PIN inválido

    {
      "code": 4006,
      "message": "PIN must be exactly 6 digits"
    }

❌ 429 Too Many Requests​

  • Cuenta bloqueada por intentos fallidos

    {
      "code": 4030,
      "message": "PIN verification blocked. Try again in 14 minutes.",
      "details": {
        "blockedUntil": "2025-01-20T15:00:00.000Z",
        "remainingMinutes": 14
      }
    }

❌ 401 Unauthorized​

  • Sin token válido

    {
      "statusCode": 401,
      "message": "Unauthorized"
    }

🔒 Sistema de intentos y bloqueos​

  • Máximo de intentos: 5 intentos fallidos antes del bloqueo
  • Tiempo de bloqueo: 15 minutos después de agotar los intentos
  • Contador de intentos: Se resetea después de una verificación exitosa
  • Información de intentos: Se proporciona en cada respuesta de error

⏱️ Gestión de sesiones aprobadas​

  • Duración de sesión: 24 horas desde la verificación exitosa
  • Timeout por inactividad: 5 minutos sin actividad
  • Vinculación JWT: La sesión se vincula al token JWT actual (JTI)
  • Auto-revocación: Las sesiones se revocan automáticamente al expirar

📝 Notas​

  • Una vez verificado el PIN, no será necesario re-verificarlo durante el tiempo de sesión
  • La sesión aprobada se vincula específicamente al token JWT actual
  • Las operaciones sensibles verificarán automáticamente la sesión aprobada
  • Consulta /auth/pin/attempts para ver estadísticas de intentos
  • Usa /auth/pin/session/status para verificar el estado de la sesión

🛡️ Rate Limiting​

Este endpoint tiene protección especial:

  • 5 intentos por 15 minutos por usuario
  • Bloqueo automático después de 5 intentos fallidos consecutivos

Importante: Una verificación exitosa creará una sesión aprobada que permitirá acceso a operaciones sensibles sin re-verificar el PIN hasta que expire.