Autenticación

Zentto utiliza JSON Web Tokens (JWT) para autenticar las solicitudes a la API. Las integraciones externas también pueden usar API keys para acceso programático.

Login

Para obtener un token JWT, enviar las credenciales al endpoint de login:

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

{
  "email": "[email protected]",
  "password": "contraseña"
}

Respuesta exitosa

{
  "ok": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "name": "Juan Pérez",
      "email": "[email protected]",
      "role": "Administrador"
    },
    "expiresIn": 3600
  }
}

Respuesta de error

{
  "ok": false,
  "message": "Credenciales inválidas"
}

La verificación de contraseña se realiza con bcrypt en Node.js. Las contraseñas nunca se envían ni almacenan en texto plano.

📸 Captura: Flujo de autenticación JWT con login y refresh

Usar el token

Incluir el token en el header Authorization de cada solicitud:

GET /api/products
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Si el token es inválido o ha expirado, la API responde con 401 Unauthorized.

Refresh token

El token principal expira en 1 hora (configurable). Para obtener uno nuevo sin re-autenticar:

POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Respuesta

{
  "ok": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...(nuevo)",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...(nuevo)",
    "expiresIn": 3600
  }
}

El refresh token tiene una vida útil de 7 días. Cada vez que se usa, se genera uno nuevo y el anterior se invalida (rotación).

API keys

Para integraciones de sistema a sistema que no involucran un usuario interactivo, se pueden usar API keys.

Crear una API key

1. Navegar a Administración → Integración → API Keys.
2. Clic en Nueva API Key.
3. Asignar un nombre descriptivo y los permisos necesarios.
4. El sistema genera la key (se muestra una sola vez).

Usar una API key

GET /api/products
X-API-Key: zk_live_abc123def456...

Las API keys tienen los siguientes atributos:

Atributo	Descripción
Nombre	Identificación descriptiva
Permisos	Módulos y acciones autorizadas
IP permitidas	Restricción por dirección IP (opcional)
Fecha de expiración	Caducidad automática (opcional)
Último uso	Fecha y hora del último request
Estado	Activa / Revocada

📸 Captura: Panel de gestión de API keys con estado y último uso

Seguridad

• Las contraseñas se hashean con bcrypt (salt + hash).
• Los tokens JWT se firman con un secreto configurado en el servidor.
• Las API keys se almacenan hasheadas en la base de datos.
• Cada intento fallido de login se registra en la bitácora de auditoría.
• Tras 5 intentos fallidos, la cuenta se bloquea temporalmente (15 minutos).
• Todas las comunicaciones van sobre HTTPS (TLS 1.2+).

Logout

Para invalidar la sesión actual:

POST /api/auth/logout
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Esto invalida tanto el token como el refresh token asociado.