Autenticación y roles

Toda la API se consume con el patrón estándar:

Authorization: Bearer <token>

Los tokens son opacos (aleatorios); en la base de datos solo se guarda su hash SHA-256, por lo que un volcado de tablas no sirve para suplantar sesiones.

La referencia de Scalar (/openapi) declara estos esquemas en OpenAPI (bearerAuth, cronSecret y webhookSecret): el botón Autorizar captura el token y lo inyecta en cada petición de prueba. Cada operación indica si necesita sesión; las públicas (login, lecturas de plano y eventos) y las de jobs salen marcadas con su esquema correspondiente.

Primer administrador (bootstrap)

Si no existe ningún administrador, POST /admins/ está abierto (sin sesión). En cuanto hay al menos uno, exige rol superadmin:

curl -X POST http://localhost:5000/admins/ \
  -H 'content-type: application/json' \
  -d '{"email":"admin@empresa.mx","nombre":"Admin","password":"secreto-largo-123","rol":"superadmin"}'

• Email normalizado (lower(email)) — la unicidad real es por minúsculas.
• Contraseña mínimo 12 caracteres, guardada con Argon2id.

Login de administrador

curl -X POST http://localhost:5000/auth/admin/login \
  -H 'content-type: application/json' \
  -d '{"email":"admin@empresa.mx","password":"secreto-largo-123"}'

Respuesta:

{ "token": "…", "refreshToken": "…" }

Login de participante

El participante pertenece a un evento, así que el login lo lleva eventoId:

curl -X POST http://localhost:5000/auth/login \
  -H 'content-type: application/json' \
  -d '{"eventoId":"<uuid>","email":"persona@empresa.mx","password":"…"}'

Autorregistro

POST /auth/registro crea al participante en precargado y dispara la verificación de email por correo (el token crudo solo viaja en el correo, nunca se persiste):

curl -X POST http://localhost:5000/auth/registro \
  -H 'content-type: application/json' \
  -d '{"eventoId":"<uuid>","email":"persona@empresa.mx","password":"…","nombreConfirmado":"Nombre Apellido"}'

Canje del enlace: POST /auth/verificar-email { "token": "…" }.

Refrescar y cerrar sesión

# Rotación de sesión: devuelve token nuevo y revoca el refresh usado.
# Reusar un refresh ya canjeado responde 401 (detección de robo).
curl -X POST http://localhost:5000/auth/refrescar \
  -H 'content-type: application/json' -d '{"refreshToken":"…"}'

# Revoca el access token en el servidor (logout real, no solo borrar local).
curl -X POST http://localhost:5000/auth/logout -H "authorization: Bearer $TOKEN"

# Validar una sesión viva
curl "http://localhost:5000/auth/sesion?token=$TOKEN"

Recuperación de contraseña

1. POST /auth/recuperar con email (y eventoId para participantes; actor indica quién pide) → envía enlace de un solo uso (24 h).
2. POST /auth/restablecer { "token": "…", "nueva": "…" }.

También existen POST /auth/password (cambio con contraseña actual) y POST /auth/admin/password para administradores.

Roles de administrador

Rol	Alcance
superadmin	Todo, incluye gestión de administradores
operador	Operación del evento: reservas, salón, check-in, notificaciones
checador	Solo escaneo en puerta e incidencias
lectura	Solo lectura

Los permisos se validan por endpoint (403 si el rol no alcanza); un token de participante nunca pasa los guards de administrador.

Límites de velocidad (rate limit)

Dos contadores por IP y minuto (ventana fija):

Variable	Default	Ámbito
RATE_LIMIT_MAX	300	Todas las rutas
RATE_LIMIT_AUTH_MAX	30	Endpoints de login

Al superarlos la API responde 429 { "error": "Demasiadas solicitudes" }. Detrás de un proxy/load balancer, activa TRUST_PROXY=true para confiar en X-Forwarded-For.

Retención

Las sesiones e intentos vencidos los purga el job diario auth.purgar (ver Jobs programados); controlan la retención las variables RETENCION_SESIONES_DIAS y RETENCION_INTENTOS_DIAS.

Siguiente paso

→ Errores y códigos