Autenticación

Zentto protege las operaciones del ERP con un JWT. En el navegador, el mecanismo principal es una cookie HttpOnly; Authorization: Bearer se mantiene como compatibilidad para clientes que no usan cookies.

Iniciar sesión

El endpoint publicado recibe usuario y clave, no email y password:

POST /v1/auth/login
Content-Type: application/json

{
  "usuario": "USUARIO",
  "clave": "contraseña",
  "companyId": 10,
  "branchId": 1
}

companyId, branchId y captchaToken son opcionales en el contrato. Tras validar credenciales, suscripción y acceso a la empresa, la API crea la cookie zentto_token con HttpOnly, SameSite=Lax y Secure en producción. El body todavía incluye token por compatibilidad durante la migración de clientes antiguos.

Una respuesta correcta incluye, entre otros campos, userId, userName, isAdmin, permisos, modulos, defaultCompany y companyAccesses. No devuelve el envoltorio ficticio { ok, data, refreshToken }.

Consumir una ruta protegida

Navegador

El navegador envía la cookie automáticamente. Las solicitudes entre orígenes deben habilitar credenciales:

await fetch("https://api.zentto.net/v1/clientes", {
  credentials: "include"
});

Cliente con Bearer

El middleware acepta el header como fallback de compatibilidad:

GET /v1/clientes
Authorization: Bearer <jwt>

La prioridad real es: __Secure-zentto_token, zentto_token, zentto_access y, finalmente, Bearer. Una solicitud sin token responde 401 con missing_token.

Renovación y cierre de sesión

El contrato y el router actuales del ERP no exponen POST /v1/auth/refresh ni POST /v1/auth/logout. La cookie emitida por el login dura dos horas; al expirar, el cliente debe volver a autenticar o usar el flujo de sesión provisto por su aplicación. No implementes integración contra rutas de refresh o logout que no existen en OpenAPI.

API keys públicas del tenant

Estas keys no sustituyen el JWT en toda la API. Sirven para que un sitio o servicio externo llame endpoints públicos del tenant mediante X-Tenant-Key, con un catálogo cerrado de scopes.

La gestión está implementada en CRM → Integraciones → API Keys públicas:

Acción	Ruta de gestión	Autenticación
Listar	GET /v1/crm/public-keys	Sesión JWT del tenant
Crear	POST /v1/crm/public-keys	Sesión JWT del tenant
Revocar	DELETE /v1/crm/public-keys/{keyId}	Sesión JWT del tenant

Al crear una key se eligen una etiqueta y uno o más scopes permitidos. El valor completo se devuelve una sola vez; después solo se conserva y muestra el prefijo. La vigencia tiene un máximo de 365 días y la key puede revocarse desde el listado.

Scopes admitidos actualmente por la ruta de creación:

• landing:lead:create
• notify:email:send
• notify:contacts:upsert
• notify:otp:send
• cache:read
• cache:write

Ejemplo de consumo en un endpoint que declare tenantKeyAuth:

POST /api/landing/register
X-Tenant-Key: <key>
Content-Type: application/json

La definición tenantKeyAuth sí está publicada en OpenAPI. Las tres rutas de gestión de /v1/crm/public-keys están verificadas en el router y en el frontend, pero todavía no aparecen como operaciones del contrato; trátalo como una brecha de contrato y no como autorización para usar la key en rutas no declaradas.

Controles de seguridad verificados

• La cookie de sesión no es accesible desde JavaScript.
• El middleware resuelve la empresa y sucursal autorizadas antes de ejecutar una ruta protegida.
• Los defaults de bloqueo son 5 intentos fallidos y 15 minutos; ambos valores son configurables.
• El login está limitado por IP y puede exigir captcha según la configuración.
• Las API keys públicas tienen scopes cerrados, caducidad y revocación.
• Nunca guardes JWT o API keys en el repositorio, documentación, logs o código del navegador.