Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/scoria02/marbes2021_backend/llms.txt

Use this file to discover all available pages before exploring further.

Every request to the Marbes API must prove identity through a signed JSON Web Token (JWT). The token carries the authenticated employee’s ID, name, role, and email. Roles are defined in the database and assigned to employees; the set of permissions a user has is resolved at runtime by querying the permisosbyuser endpoint. Two middleware functions—authMiddleware for standard endpoints and authOrSolicitudToken for public credit-application links—enforce authentication at the route level.

​
Authentication flow

1

Employee logs in

The client sends credentials (email or name, plus password) to POST /api/auth/login. The server validates the credentials and returns a signed JWT.
2

Token is attached to requests

The client includes the token in the Authorization header of every subsequent request:
Authorization: Bearer <token>
3

authMiddleware validates the token

For protected routes, authMiddleware extracts the token from the Authorization header, verifies it against JWT_SECRET, and attaches the decoded payload to req.user. If the token is missing, malformed, or expired, the request is rejected with 401.
4

Role and permissions are available

Once the middleware populates req.user, controllers can read req.user.role to make authorization decisions, or the client can call GET /api/rrhh/permisosbyuser to fetch the full permission list for the current user.

​
The user object on req.user

After authMiddleware validates a token, it attaches the following object to the Express request: 
req.user = {
  id: string;    // Employee UUID
  name: string;  // Employee display name
  role: string;  // Primary role name (from JWT payload)
  email: string; // Employee email address
}
The JWT payload is set at login time. If a role is reassigned after the token is issued, the change will not be reflected until the employee logs in again and receives a new token.

​
Role system

Roles are stored in the database and assigned to employees through the HR module. Each role has a nombre (name), a descripcion, and an activo flag. An employee can hold multiple roles; each assignment records the fecha_asignacion and asignado_por (who granted it). 
interface RolEmpleado {
  id: string;
  nombre: string;
  descripcion: string;
  activo: boolean;
  fecha_asignacion: string;
  asignado_por: string;
}

​
Managing roles

EndpointMethodDescription
GET /api/rrhh/rolesGETList all roles defined in the system
POST /api/rrhh/rolesPOSTCreate a new role
PUT /api/rrhh/user/roles/editarPUTAssign or update roles for an employee
POST /api/rrhh/roles/permisosPOSTAssign permissions to a role
GET /api/rrhh/roles/:rolNombre/analisisGETInspect permissions assigned to a role

​
Permissions

Permissions are assigned to roles, not to individual employees. To retrieve the resolved permissions for the currently authenticated user, call: 
GET /api/rrhh/permisosbyuser
Authorization: Bearer <token>
This endpoint reads req.user.id from the validated JWT and returns the set of permissions inherited through the employee’s assigned roles. To list all permissions defined in the system: 
GET /api/rrhh/permisos
Authorization: Bearer <token>

​
Middleware reference

​
authMiddleware

Applied to all standard API endpoints. It:
  1. Reads the Authorization header and checks for Bearer <token> format.
  2. Verifies the JWT signature using the JWT_SECRET environment variable.
  3. Populates req.user with { id, name, role, email }.
  4. Calls next() on success or responds 401 on failure.
// Usage in routes
router.get('/empleados', authMiddleware, validate, handler);
All endpoints under /api/rrhh and /api/negocios require authMiddleware. Sending a request without a valid Authorization header will always return 401 Acceso denegado. No se proveyó token.

​
authOrSolicitudToken

Used on endpoints that must be accessible both to authenticated employees and to external users following a one-time credit application link. It tries JWT authentication first; if that fails, it falls back to a solicitud link token. 
# Option A: authenticated employee
Authorization: Bearer <jwt>

# Option B: one-time link token (credit applicant)
X-Solicitud-Token: <link-token>
If a link token is provided, the middleware looks it up in the database and validates three conditions:
  • The token exists in the solicitudes table.
  • The usado (used) flag is false.
  • The expira_en (expiry) timestamp is in the future.
On success it populates req.solicitudLink with { id, cliente_id, expira_en, usado } instead of req.user.
authOrSolicitudToken is currently applied to the economic activity catalog (GET /api/negocios/actividad_economica) and the countries catalog (GET /api/negocios/paises), which credit applicants need when filling in a credit application form.

​
Error responses

ConditionStatusMessage
No Authorization header401Acceso denegado. No se proveyó token.
Token fails JWT verification or expired401Token inválido o expirado.
Token structure is not an object401Token inválido: estructura incorrecta.
No JWT and no solicitud token provided401Se requiere autenticación (Bearer token) o token de solicitud (X-Solicitud-Token o campo token).
Solicitud token not found in DB401Token de solicitud no encontrado.
Solicitud token already used401Este link ya fue utilizado.
Solicitud token expired401El link ha expirado.

​
Employee status values

An employee’s estatus field controls whether they can log in and operate in the system. The values are defined as strings in the database:
ValueMeaning
activoEmployee is active and can authenticate
desactivoEmployee account is deactivated
suspendidoEmployee is temporarily suspended
The API does not automatically block authentication based on estatus—that check is enforced in the login controller. Always verify that a user’s estatus is activo before granting access in custom integrations.

​
Login validation rules

The login endpoint accepts any one of the following identifiers alongside password:
  • email — must be a valid email address
  • name — non-empty username string
  • code — non-empty code string
If none of the identifiers are provided, the validator returns 400 with the message: Se requiere al menos un identificador: email, username o code.

Build docs developers (and LLMs) love

Get started for freeTalk to us