Autenticación

La API está protegida con JWT (Bearer token) de forma global. Salvo POST /auth/login (público), todos los endpoints requieren un token válido.

Obtener el token

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

{
  "nickname": "<usuario>",
  "password": "<contraseña>"
}

Respuesta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "role": "admin",
  "nickname": "<usuario>"
}

Incluir el token en los requests

Envía el access_token en el header Authorization con el esquema Bearer:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Si el header falta o el token es inválido/expirado, la API responde 401 Unauthorized.

Roles

Rol	Qué puede hacer
superadmin	Acceso total. No puede crearse vía API ni ser desactivado.
admin	Gestión de usuarios y tenants; opera sobre cualquier tenant.
tenant	Solo puede operar sobre su propio tenantNit.

La autorización combina dos capas:

• Roles por endpoint — cada endpoint declara qué roles lo pueden invocar.
• Aislamiento por tenant — en los endpoints con :nit en la ruta, un usuario tenant solo pasa si el :nit de la ruta coincide con su propio tenantNit; de lo contrario recibe 403 Forbidden. admin y superadmin no tienen esta restricción.

Cambio de contraseña

Cualquier usuario autenticado puede cambiar su propia contraseña:

PATCH /auth/change-password
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "currentPassword": "<contraseña actual>",
  "newPassword": "<nueva contraseña>"
}

Duración del token

La vigencia del token se configura con la variable de entorno JWT_EXPIRES_IN (valor por defecto: 1d — un día). Acepta los formatos de la librería ms (1d, 7d, 12h, etc.). El secreto de firma se define en JWT_SECRET.

Referencia

Para probar el login y obtener un token interactivamente, usa la API Reference (Swagger) y el botón Authorize.