Skip to main content
Users authenticate with a nombre_usuario / contrasena pair and are assigned a role of either admin or cajero. Passwords are hashed with bcrypt (10 rounds) before storage and are never returned in any API response.
Only users with the admin role can create, update, list, view, or delete users. A cajero user that calls any endpoint in this resource will receive a 403 Forbidden response.
Soft delete is used throughout. Deleting a user sets borrado_en to the current timestamp. The record is never physically removed from the database.

​
POST /api/usuarios

Create a new user. Authentication: Bearer JWT required
Required role: admin

​
Request body

​
nombre
string
required
Full display name. Between 3 and 60 characters.
​
nombre_usuario
string
required
Unique login username. Between 3 and 30 characters. Only lowercase letters, digits, and underscores are allowed (^[a-z0-9_]+$). Must be unique across all active users.
​
contrasena
string
required
Plain-text password. Minimum 6 characters. It is hashed with bcrypt before being stored and is never returned.
​
rol
string
required
Role to assign. Accepted values: admin, cajero.

​
Response

Returns the created user object (201 Created). The contrasena field is excluded.
​
id
string
Unique identifier with the format usr_<16-char nanoid> (e.g. usr_abc123def456ghi7).
​
nombre
string
Full display name.
​
nombre_usuario
string
Login username.
​
rol
string
Assigned role (admin or cajero).
​
creado_en
string (ISO 8601)
Creation timestamp.
​
actualizado_en
string (ISO 8601)
Last update timestamp.

​
Error codes

StatusMeaning
401Missing or invalid JWT
403Caller does not have the admin role
409nombre_usuario is already in use by an active user

​
Example

curl -X POST http://localhost:3000/api/usuarios \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Juan Pérez",
    "nombre_usuario": "juanperez",
    "contrasena": "Password123!",
    "rol": "cajero"
  }'

{
  "id": "usr_abc123def456ghi7",
  "nombre": "Juan Pérez",
  "nombre_usuario": "juanperez",
  "rol": "cajero",
  "creado_en": "2026-03-18T14:00:00.000Z",
  "actualizado_en": "2026-03-18T14:00:00.000Z"
}

​
GET /api/usuarios

Return all active users. Authentication: Bearer JWT required
Required role: admin

​
Request parameters

No parameters.

​
Response

Returns an array of user objects (200 OK), ordered by creado_en ascending. Only records where borrado_en IS NULL are included. The contrasena field is excluded from every item.

​
Example

curl http://localhost:3000/api/usuarios \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "usr_abc123def456ghi7",
    "nombre": "Juan Pérez",
    "nombre_usuario": "juanperez",
    "rol": "cajero",
    "creado_en": "2026-03-18T14:00:00.000Z",
    "actualizado_en": "2026-03-18T14:00:00.000Z"
  }
]

​
GET /api/usuarios/:id

Return a single active user by ID. Authentication: Bearer JWT required
Required role: admin

​
Request parameters

​
id
string
required
The user ID (format: usr_<nanoid>).

​
Response

Returns the user object (200 OK) without contrasena, or 404 Not Found if the user does not exist or has been soft-deleted.

​
Example

curl http://localhost:3000/api/usuarios/usr_abc123def456ghi7 \
  -H "Authorization: Bearer <token>"

​
PUT /api/usuarios/:id

Fully update a user. All body fields are optional; only the fields you send are changed. Authentication: Bearer JWT required
Required role: admin

​
Request parameters

​
id
string
required
The user ID to update.
​
nombre
string
New full display name. Between 3 and 60 characters.
​
nombre_usuario
string
New login username. Between 3 and 30 characters. Only lowercase letters, digits, and underscores. Must be unique.
​
contrasena
string
New password. Minimum 6 characters. Hashed with bcrypt before storage.
​
rol
string
New role. Accepted values: admin, cajero.

​
Response

Returns the updated user object (200 OK) without contrasena. actualizado_en is always refreshed.

​
Error codes

StatusMeaning
401Missing or invalid JWT
403Caller does not have the admin role
404User not found or already deleted
409nombre_usuario is already in use by another active user

​
Example

curl -X PUT http://localhost:3000/api/usuarios/usr_abc123def456ghi7 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"rol": "admin"}'

​
DELETE /api/usuarios/:id

Soft-delete a user. Authentication: Bearer JWT required
Required role: admin
Only admin users can delete other users. This operation is irreversible through the API — a deleted user cannot log in and will not appear in any list response.

​
Request parameters

​
id
string
required
The user ID to delete.

​
Response

Returns 204 No Content on success. No body is returned.

​
Error codes

StatusMeaning
401Missing or invalid JWT
403Caller does not have the admin role
404User not found or already deleted

​
Example

curl -X DELETE http://localhost:3000/api/usuarios/usr_abc123def456ghi7 \
  -H "Authorization: Bearer <token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us