Users API — Create, Update, and Manage User Accounts

The Users API manages the operator accounts that power PermisosQR. Two roles exist: super_admin (full access to all resources) and admin_operator (can enable and return permissions, limited to their own records). Most write operations are gated behind the super_admin role; any authenticated user can read their own profile and change their own password.

GET /api/users

Returns an array of all user accounts in the system. No pagination is applied — the full list is returned in a single response. Auth required: Bearer — Super Admin only Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Ana Torres",
      "email": "ana@example.com",
      "role": "super_admin",
      "is_active": true,
      "created_at": "2024-01-01T10:00:00.000Z",
      "updated_at": "2024-01-01T10:00:00.000Z"
    },
    {
      "id": 2,
      "name": "Carlos Ruiz",
      "email": "carlos@example.com",
      "role": "admin_operator",
      "is_active": true,
      "created_at": "2024-01-02T09:30:00.000Z",
      "updated_at": "2024-01-02T09:30:00.000Z"
    }
  ]
}

Show User object fields

integer

Unique numeric user ID.

name

string

Display name.

string

Unique email address used for login.

role

string

Either super_admin or admin_operator.

is_active

boolean

When false, the account cannot log in or perform any action.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-update timestamp.

Error responses

Status	Condition
`403`	Authenticated user does not have the `super_admin` role

GET /api/users/:id

Fetches a single user by their numeric ID. Any authenticated user can call this endpoint; however, operators should only request their own ID. The response never includes the password hash. Auth required: Bearer Path parameter: id — integer user ID Response 200

{
  "success": true,
  "data": {
    "id": 2,
    "name": "Carlos Ruiz",
    "email": "carlos@example.com",
    "role": "admin_operator",
    "is_active": true,
    "created_at": "2024-01-02T09:30:00.000Z",
    "updated_at": "2024-01-02T09:30:00.000Z"
  }
}

Error responses

Status	Condition
`401`	Bearer token missing or invalid
`404`	No user with the given ID exists

POST /api/users

Creates a new user account. The password is hashed with bcrypt before storage — the hash is never returned. All four fields are required. Auth required: Bearer — Super Admin only

name

string

required

Display name for the new account.

string

required

Unique email address. Used as the login identifier.

password

string

required

Plaintext password. Stored as a bcrypt hash. Minimum 6 characters recommended.

role

string

required

Account role. Must be either super_admin or admin_operator.

Response 201

{
  "success": true,
  "data": {
    "id": 3,
    "name": "María López",
    "email": "maria@example.com",
    "role": "admin_operator",
    "is_active": true,
    "created_at": "2024-01-16T08:00:00.000Z"
  }
}

Error responses

Status	Condition
`400`	Any of the four required fields is missing
`403`	Authenticated user is not a Super Admin
`409`	Email address is already registered

curl -X POST http://localhost:4000/api/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "María López",
    "email": "maria@example.com",
    "password": "securepassword",
    "role": "admin_operator"
  }'

PUT /api/users/:id

Updates one or more fields on an existing user account. All body fields are optional — only supplied fields are updated. This endpoint cannot be used to change a password; use PATCH /api/users/:id/password or PATCH /api/users/:id/reset-password instead. Auth required: Bearer — Super Admin only Path parameter: id — integer user ID

name

string

New display name.

string

New email address. Must be unique across all users.

role

string

New role. One of super_admin or admin_operator.

is_active

boolean

Set to false to deactivate the account without deleting it. A deactivated user cannot log in.

Response 200 — Updated User object (same shape as POST /api/users response). Error responses

Status	Condition
`403`	Authenticated user is not a Super Admin
`404`	No user with the given ID exists
`409`	Updated email is already taken by another account

PATCH /api/users/:id/password

Allows any authenticated user to change their own account password. The currentPassword field is verified before applying the change, providing protection against session hijacking. Auth required: Bearer — any authenticated user (for their own ID) Path parameter: id — integer user ID (must match the authenticated user’s own ID)

currentPassword

string

required

The account’s current plaintext password. Used to confirm identity before applying the change.

newPassword

string

required

The desired new plaintext password. Will be bcrypt-hashed before storage.

Response 200

{ "success": true, "message": "Contraseña actualizada exitosamente" }

Error responses

Status	Condition
`400`	Either `currentPassword` or `newPassword` is missing; or `currentPassword` does not match the stored hash
`404`	No user with the given ID exists

The server does not enforce that the authenticated user can only change their own password — the id path parameter is used directly. Use role-based or ownership checks in your frontend to restrict this action to self-service only.

PATCH /api/users/:id/reset-password

Forcefully sets a new password for any user account without requiring knowledge of the current password. Intended for administrators resetting a locked-out user’s credentials. Password must be at least 6 characters. Auth required: Bearer — Super Admin only Path parameter: id — integer user ID

newPassword

string

required

The new plaintext password to set. Minimum 6 characters.

Response 200

{ "success": true, "message": "Contraseña restablecida exitosamente" }

Error responses

Status	Condition
`400`	`newPassword` is missing or shorter than 6 characters
`403`	Authenticated user is not a Super Admin
`404`	No user with the given ID exists

DELETE /api/users/:id

Deactivates a user account by setting is_active to false. The record is retained in the database to preserve audit trail integrity — all historical permission records linked to this user remain intact. A deactivated user cannot log in or perform any action. Auth required: Bearer — Super Admin only Path parameter: id — integer user ID Response 200

{ "success": true, "message": "Usuario desactivado" }

Error responses

Status	Condition
`403`	Authenticated user is not a Super Admin
`404`	No user with the given ID exists

This endpoint performs a soft-delete. The user row is never removed from the database; only is_active is set to false. To reactivate the account, use PUT /api/users/:id with { "is_active": true }.

Overview

Endpoints

Users API — Create, Update, and Manage User Accounts

GET /api/users

GET /api/users/:id

POST /api/users

PUT /api/users/:id

PATCH /api/users/:id/password

PATCH /api/users/:id/reset-password

DELETE /api/users/:id

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/users

​GET /api/users/:id

​POST /api/users

​PUT /api/users/:id

​PATCH /api/users/:id/password

​PATCH /api/users/:id/reset-password

​DELETE /api/users/:id

Build docs developers (and LLMs) love

GET /api/users

GET /api/users/:id

POST /api/users

PUT /api/users/:id

PATCH /api/users/:id/password

PATCH /api/users/:id/reset-password

DELETE /api/users/:id