Usuarios — User Accounts, Roles & Module Access

The Users API controls who can log in to the system and what they can do. Access control is organized into three layers: users (credentials + linked employee), roles (named permission sets), and modules (navigation items available to each role). Permissions are stored as a bitmask in the permisos field of each role.

All endpoints require a valid Bearer token unless otherwise noted. Include Authorization: Bearer <token> in every request header.

Users

List active users

GET /api/usuarios Returns all users where vigente = true.

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios' \
  --header 'Authorization: Bearer <token>'

Response fields

number

Unique user ID.

nombre

string

Display name.

dni

string

Identity document number.

string

vigente

boolean

true if the account is active.

rol

object

Assigned role.

Show RolResponse properties

string

Role identifier (e.g., ADMIN, TECNICO).

nombre

string

Human-readable role name.

descripcion

string

Role description.

permisos

number

Bitmask integer encoding the set of permissions granted. See Permission bitmask reference.

empleado

object

Linked employee record. See EmpleadoResponse for field details.

Create a user

POST /api/usuarios Creates a new user account linked to an existing employee.

nombre

string

required

Display name for the user.

dni

string

required

Identity document number.

string

required

password

string

required

Initial password. Stored as a bcrypt hash.

idRol

string

required

Role ID to assign (e.g., ADMIN, TECNICO). Use GET /api/usuarios/roles to retrieve valid IDs.

empleadoId

number

required

ID of the employee record to link. Each employee can only be linked to one active user.

curl --request POST \
  --url 'https://your-api.example.com/api/usuarios' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nombre": "Luis Torres",
    "dni": "72345678",
    "email": "ltorres@empresa.pe",
    "password": "SecurePass123!",
    "idRol": "TECNICO",
    "empleadoId": 5
  }'

Get current user

GET /api/usuarios/usuario Returns the profile of the authenticated user derived from the Bearer token. Useful for populating the UI with the logged-in user’s details.

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios/usuario' \
  --header 'Authorization: Bearer <token>'

Get user by ID

GET /api/usuarios/{id} Returns a single user record by ID.

number

required

Numeric user ID.

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios/12' \
  --header 'Authorization: Bearer <token>'

Update a user

PUT /api/usuarios/{id} Updates user account details.

number

required

Numeric ID of the user to update.

All body fields from Create a user are accepted. Only the fields you include are updated.

curl --request PUT \
  --url 'https://your-api.example.com/api/usuarios/12' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idRol": "SUPERVISOR"
  }'

Delete a user

DELETE /api/usuarios/{id} Soft-deletes a user account. The record is retained but the user can no longer log in.

number

required

Numeric ID of the user to deactivate.

curl --request DELETE \
  --url 'https://your-api.example.com/api/usuarios/12' \
  --header 'Authorization: Bearer <token>'

Roles

Roles define what actions a user is permitted to take. The permisos field is a bitmask — an integer computed by adding together individual permission values.

List active roles

GET /api/usuarios/roles Returns all roles that are currently active.

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios/roles' \
  --header 'Authorization: Bearer <token>'

Create a role

POST /api/usuarios/roles Creates a new role with a set of permissions encoded as a bitmask.

string

required

Unique string identifier for the role (e.g., TECNICO, SUPERVISOR). Used as the foreign key in user records.

nombre

string

required

Human-readable role name.

descripcion

string

Description of the role’s purpose.

permisos

number

required

Bitmask integer encoding the granted permissions. Sum the values of all desired permissions. See Permission bitmask reference.

curl --request POST \
  --url 'https://your-api.example.com/api/usuarios/roles' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "TECNICO",
    "nombre": "Técnico",
    "descripcion": "Field technician with execution rights",
    "permisos": 37
  }'

permisos: 133 = REGISTRAR_PENDIENTE (1) + VER_DETALLE_PENDIENTE (4) + COMENZAR_TRABAJO (128) = 133. See the full bitmask table below.

Update a role

PUT /api/usuarios/roles/{id} Updates an existing role’s name, description, or permissions.

string

required

The string ID of the role to update (e.g., TECNICO).

curl --request PUT \
  --url 'https://your-api.example.com/api/usuarios/roles/TECNICO' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "permisos": 101
  }'

Delete a role

DELETE /api/usuarios/roles/{id} Deletes a role. This operation is blocked if any active users are currently assigned to the role.

string

required

The string ID of the role to delete.

The API will return an error if users are currently assigned to this role. Reassign or deactivate those users before deleting the role.

curl --request DELETE \
  --url 'https://your-api.example.com/api/usuarios/roles/TECNICO' \
  --header 'Authorization: Bearer <token>'

Modules

Modules represent navigation items or feature areas within the application. Each role is associated with a set of modules that controls what the user can see.

List all modules

GET /api/usuarios/modulos Returns all registered modules.

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios/modulos' \
  --header 'Authorization: Bearer <token>'

Response fields

number

Module ID.

nombre

string

Module name.

descripcion

string

Module description.

icono

string

Icon identifier (e.g., home, users).

ruta

string

Application route (e.g., /dashboard).

moduloPadre

object

Parent module, if this is a sub-module. Same structure as ModuloResponse. null for top-level modules.

vigente

boolean

true if the module is active.

Get module by ID

GET /api/usuarios/modulos/{id} Returns a single module record.

number

required

Numeric module ID.

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios/modulos/3' \
  --header 'Authorization: Bearer <token>'

Get modules for a role

GET /api/usuarios/modulos/rol/{id} Returns the list of modules accessible to a specific role.

string

required

The role ID (e.g., ADMIN, TECNICO).

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios/modulos/rol/TECNICO' \
  --header 'Authorization: Bearer <token>'

Get modules for current user

GET /api/usuarios/modulos/usuario Returns the list of modules accessible to the authenticated user, based on their assigned role.

curl --request GET \
  --url 'https://your-api.example.com/api/usuarios/modulos/usuario' \
  --header 'Authorization: Bearer <token>'

Create a module

POST /api/usuarios/modulos Registers a new application module.

nombre

string

required

Module name.

descripcion

string

Description of what this module provides.

icono

string

Icon identifier string (e.g., home, clipboard-list).

ruta

string

Application route path (e.g., /pendientes).

moduloPadreId

number

ID of the parent module if this is a sub-module. Pass null for top-level modules.

curl --request POST \
  --url 'https://your-api.example.com/api/usuarios/modulos' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nombre": "Pendientes",
    "descripcion": "Work order management",
    "icono": "clipboard-list",
    "ruta": "/pendientes",
    "moduloPadreId": null
  }'

Update a module

PUT /api/usuarios/modulos/{id} Updates an existing module’s details.

number

required

Numeric ID of the module to update.

curl --request PUT \
  --url 'https://your-api.example.com/api/usuarios/modulos/3' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "icono": "wrench",
    "ruta": "/ordenes"
  }'

Sync modules for a role

POST /api/usuarios/modulos/sync Replaces the full set of modules assigned to a role. Any modules not included in moduloIds will be unlinked from the role.

rolId

string

required

The role ID to update module access for (e.g., ADMIN).

moduloIds

number[]

required

Complete list of module IDs to assign to the role. This is a full replacement, not an append.

This operation replaces the entire module list for the role. Any previously assigned modules not included in moduloIds will lose access.

curl --request POST \
  --url 'https://your-api.example.com/api/usuarios/modulos/sync' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idRol": "TECNICO",
    "moduloIds": [1, 3, 5]
  }'

Delete a module

DELETE /api/usuarios/modulos/{id} Soft-deletes a module by setting vigente = false.

number

required

Numeric ID of the module to deactivate.

curl --request DELETE \
  --url 'https://your-api.example.com/api/usuarios/modulos/3' \
  --header 'Authorization: Bearer <token>'

Permission bitmask reference

The permisos field in a role is a Long integer where each bit value maps to a specific permission. To grant multiple permissions, sum their bit values.

Bit value	Permission	Description
1	`REGISTRAR_PENDIENTE`	Create new work orders
2	`EDITAR_PENDIENTE`	Edit existing work order fields
4	`VER_DETALLE_PENDIENTE`	View full detail of a single work order
8	`VER_TODOS_PENDIENTES`	List and search all work orders
16	`ASIGNAR_TECNICO`	Assign a technician to a work order
32	`ASIGNAR_PPOE`	Assign PPPoE credentials
64	`ASIGNAR_VLAN`	Assign VLAN configuration
128	`COMENZAR_TRABAJO`	Start field work (move to EN_PROGRESO)
256	`PARAR_TRABAJO`	Pause field work
512	`CONTINUAR_TRABAJO`	Resume paused field work
1024	`FINALIZAR_TRABAJO`	Mark field work as finished
2048	`VER_PENDIENTES_HISTORIAL`	View all work orders in history
4096	`REVISAR_GASTOS`	Review associated expenses
8192	`REVISAR_FINALIZADOS`	Review finalized work orders

Example calculations:

Full admin access: 1 + 2 + 4 + 8 + 16 + 32 + 64 + 128 + 256 + 512 + 1024 + 2048 + 4096 + 8192 = 16383
Technician (start/stop work + view detail): 128 + 256 + 512 + 1024 + 4 = 1924
Read-only viewer: 4 + 8 + 2048 = 2060

To check whether a user has a given permission in your frontend code, use a bitwise AND: (permisos & 128) !== 0 returns true if COMENZAR_TRABAJO is granted.

Authentication

Work Orders

People & Organization

Catalog & Payments

System

Usuarios — User Accounts, Roles & Module Access

Users

List active users

Response fields

Create a user

Get current user

Get user by ID

Update a user

Delete a user

Roles

List active roles

Create a role

Update a role

Delete a role

Modules

List all modules

Response fields

Get module by ID

Get modules for a role

Get modules for current user

Create a module

Update a module

Sync modules for a role

Delete a module

Permission bitmask reference

Build docs developers (and LLMs) love

Authentication

Work Orders

People & Organization

Catalog & Payments

System

Documentation Index

​Users

​List active users

​Response fields

​Create a user

​Get current user

​Get user by ID

​Update a user

​Delete a user

​Roles

​List active roles

​Create a role

​Update a role

​Delete a role

​Modules

​List all modules

​Response fields

​Get module by ID

​Get modules for a role

​Get modules for current user

​Create a module

​Update a module

​Sync modules for a role

​Delete a module

​Permission bitmask reference

Build docs developers (and LLMs) love

Users

List active users

Response fields

Create a user

Get current user

Get user by ID

Update a user

Delete a user

Roles

List active roles

Create a role

Update a role

Delete a role

Modules

List all modules

Response fields

Get module by ID

Get modules for a role

Get modules for current user

Create a module

Update a module

Sync modules for a role

Delete a module

Permission bitmask reference