Passwordless - JAAK

Descripción General

El módulo Passwordless de JAAK proporciona autenticación biométrica facial sin contraseñas a través de una API REST completa.

Versión del Documento: 1.0 | Última Actualización: Noviembre 2024 | Versión API: v1

Autenticación

Todos los endpoints requieren autenticación mediante API Key usando el header ApiKeyAuth.

URLs Base

Gestión de Usuarios

1. Listar Usuarios

GET /api/v1/passwordless/client

• Soporta filtrado por estado, nombre, ID externo y rangos de fecha
• Incluye paginación con límites configurables

2. Obtener Detalles de Usuario

GET /api/v1/passwordless/client/:id

• Retorna perfil completo del usuario incluyendo imágenes y metadata

3. Actualizar Usuario

PUT /api/v1/passwordless/client/:id

• Modifica nombre y estado; acepta headers de geolocalización

4. Eliminar Usuario

DELETE /api/v1/passwordless/client/:id

• Eliminación permanente (irreversible)

Enrollment (Registro Biométrico)

Enrollment por Video

POST /api/v1/passwordless/client/enroll

• Acepta video base64 (2-5 segundos, mínimo 720p)
• Retorna perfil de usuario con seguimiento de eventos

Enrollment por Imagen

POST /api/v1/passwordless/client/face-enroll

• Requiere formato JPG/PNG, resolución mínima 640x480
• El rostro debe ser frontal, centrado y sin obstrucciones

Verificación de Identidad

Verificación por Video

POST /api/v1/passwordless/client/verify

Verificación por Imagen

POST /api/v1/passwordless/client/face-verify

Ambos buscan en registros existentes y confirman coincidencias de identidad.

Búsqueda Facial

Búsqueda por Imagen

POST /api/v1/passwordless/client/facial

• Acepta parámetro rankingTop para cantidad de resultados
• Retorna coincidencias ordenadas por distancia de similitud

Búsqueda por Vector

POST /api/v1/passwordless/client/faces

• Usa vectores de características pre-calculados (128-512 dimensiones)
• Permite procesamiento rápido en lotes

Eventos y Auditoría

Listar Eventos

GET /api/v1/passwordless/event

• Filtrar por acción, estado, tiempo de procesamiento, rangos de fecha

Detalles de Evento

GET /api/v1/passwordless/event/:id

• Rastro de auditoría completo con estado a nivel de recurso

Estadísticas

• Conteo de Solicitudes por Tiempo - Análisis granular (minuto/hora/día)
• Análisis de Tiempo de Procesamiento - Promedio, moda y distribución

Mejores Prácticas

Seguridad

• Nunca exponer API keys en código frontend
• Rotar regularmente
• Siempre usar HTTPS

Headers

• Incluir Request-Id único (UUID v4)
• Proporcionar geolocalización cuando esté disponible

Calidad de Medios

• Asegurar iluminación uniforme
• Rostros frontales centrados
• Respetar resoluciones mínimas indicadas

Manejo de Errores

• Implementar lógica de reintento con backoff exponencial
• Registrar IDs de eventos para solución de problemas

Estructura de Respuesta

Las respuestas estándar incluyen: eventId, requestId, processTime (milisegundos) y objetos de usuario/evento.

Códigos HTTP

• 200 - Éxito
• 400 - Solicitud incorrecta
• 401 - No autorizado
• 404 - No encontrado
• 500 - Error del servidor

Casos de Uso Comunes

• Sistemas de login biométrico
• Control de acceso físico
• Seguimiento de asistencia
• Detección de duplicados / prevención de fraude