Users API — Account Management and Profiles in PortalHub - PortalHub

The Users API covers two closely related modules: usuarios (account management) and perfil (profile data). Account operations—creating, updating, disabling, and deleting users—are restricted to Administrators (role 1). Profile reads and updates are available to any authenticated user acting on their own record. All endpoints communicate via JSON unless otherwise noted. The server uses PHP sessions for authentication; your client must send a valid session cookie on every request.

Role constants

Constant	`id_rol`	Description
`ROL_ADMIN`	`1`	Full administrative access
`ROL_ASESOR`	`2`	Advisor — manages assigned clients
`ROL_CLIENTE`	`3`	End-client — limited to own data

GET /backend/modules/usuarios/listar.php

List all users registered in the system, including their role name and account status. Required role: Admin (1) or Asesor (2)

Advisors can call this endpoint to look up client id_usuario values, but they have no write permissions over user records.

Request

No request body. No query parameters required.

curl -X GET https://your-domain.com/backend/modules/usuarios/listar.php \
  -H "Cookie: PHPSESSID=<your_session_id>"

Response

{
  "status": 200,
  "message": "Usuarios obtenidos",
  "data": [
    {
      "id_usuario": 3,
      "correo": "cliente@empresa.com",
      "numero_cliente": "CLI-001",
      "estado": "activo",
      "fecha_registro": "2024-01-15 10:30:00",
      "nombre_rol": "Cliente"
    }
  ]
}

id_usuario

integer

Auto-incremented primary key for the user record.

correo

string

The user’s unique email address used for login.

numero_cliente

string | null

Optional client reference number. Unique across all users.

estado

enum

Account status: activo or inactivo.

fecha_registro

timestamp

UTC timestamp of when the account was created.

nombre_rol

string

Human-readable role name from cat_roles (e.g., "Admin", "Asesor", "Cliente").

Error responses

HTTP	Message
`401`	No autorizado. Inicie sesión Primero.
`403`	Acceso denegado. Permisos insuficientes.
`500`	Error en el servidor: `<detail>`

POST /backend/modules/usuarios/crear.php

Create a new user account. The new account is created with require_password_change = 1, forcing the user to set their own password on first login. Required role: Admin (1) only

Request body

correo

string

required

A unique, valid email address for the new user. Duplicate emails are rejected with HTTP 400.

password

string

required

The initial password. Stored as a bcrypt hash. The user will be prompted to change this on first login.

id_rol

integer

required

Role assignment: 1 = Admin, 2 = Asesor, 3 = Cliente.

numero_cliente

string

Optional client reference number. Must be unique system-wide if provided.

curl -X POST https://your-domain.com/backend/modules/usuarios/crear.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "correo": "nuevo@empresa.com",
    "password": "TempPass#2024",
    "id_rol": 3,
    "numero_cliente": "CLI-042"
  }'

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`400`	Formato de correo inválido
`400`	El correo ya está registrado
`401`	No autorizado. Inicie sesión Primero.
`403`	Acceso denegado. Permisos insuficientes.
`405`	Método no permitido
`500`	Error en el servidor: `<detail>`

PUT /backend/modules/usuarios/actualizar.php

Update an existing user’s email, role, status, and optional client number. Optionally set a new temporary password (which also sets require_password_change = 1). Required role: Admin (1) only

This endpoint expects an HTTP PUT request, not POST. Sending POST will return HTTP 405.

Request body

id_usuario

integer

required

The ID of the user to update.

correo

string

required

New or existing email address. Must be unique across all users except the target record.

id_rol

integer

required

Updated role: 1 = Admin, 2 = Asesor, 3 = Cliente.

estado

string

required

Must be one of "activo" or "inactivo". Any other value returns HTTP 400.

numero_cliente

string

Optional client reference number. Must be unique if provided.

temp_password

string

Optional. When provided, the password is hashed and stored, and require_password_change is set to 1.

curl -X PUT https://your-domain.com/backend/modules/usuarios/actualizar.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_usuario": 7,
    "correo": "actualizado@empresa.com",
    "id_rol": 3,
    "estado": "activo",
    "numero_cliente": "CLI-042",
    "temp_password": "NuevoTemp#99"
  }'

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`400`	Formato de correo inválido
`400`	Estado no válido
`400`	El correo ya está registrado por otro usuario
`400`	El número de cliente ya está registrado por otro usuario
`404`	Usuario no encontrado o sin cambios
`405`	Método no permitido
`500`	Ocurrió un error interno al actualizar el usuario

DELETE /backend/modules/usuarios/eliminar.php

Permanently delete a user record. This action is irreversible. Required role: Admin (1) only

Query parameters

integer

required

The id_usuario of the user to delete.

Deletion cascades to associated reset_logs and cliente_asesor records via ON DELETE CASCADE foreign keys. Ensure the user has no active services or pending payments before deleting.

curl -X DELETE "https://your-domain.com/backend/modules/usuarios/eliminar.php?id=7" \
  -H "Cookie: PHPSESSID=<your_session_id>"

Error responses

HTTP	Message
`400`	ID de usuario no proporcionado
`404`	Usuario no encontrado
`405`	Método no permitido
`500`	Error en el servidor: `<detail>`

POST /backend/modules/usuarios/gestionar_estado.php

Activate or deactivate a user account without deleting the record. Deactivated users (inactivo) cannot log in. Required role: Admin (1) only

Request body

id_usuario

integer

required

The ID of the user whose status will change.

accion

string

Action to perform. Use "activar" to enable the account or "desactivar" to disable it. Defaults to "desactivar" if omitted.

curl -X POST https://your-domain.com/backend/modules/usuarios/gestionar_estado.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{"id_usuario": 7, "accion": "activar"}'

Error responses

HTTP	Message
`400`	ID de usuario no proporcionado
`404`	Usuario no encontrado o ya se encontraba en ese estado
`405`	Método no permitido
`500`	Error en el servidor: `<detail>`

POST /backend/modules/usuarios/reset_password_admin.php

Generate a random 10-character temporary password for a user and set require_password_change = 1. The temporary password is returned in plaintext in the response once — it is never stored in plaintext. An audit entry is inserted into reset_logs. Required role: Admin (1) only

The temporary_password value in the response is the only time this credential appears in plaintext. Deliver it to the user via a secure channel immediately — it cannot be retrieved again.

Request body

id_usuario

integer

required

The ID of the user whose password will be reset.

curl -X POST https://your-domain.com/backend/modules/usuarios/reset_password_admin.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{"id_usuario": 7}'

temporary_password

string

A cryptographically random 10-character string drawn from alphanumeric and special characters (0-9, a-z, A-Z, !@#$%^&*). Only ever returned once.

Error responses

HTTP	Message
`400`	Faltan campos requeridos
`404`	Usuario no encontrado
`405`	Método no permitido
`500`	Error en el servidor: `<detail>`

GET /backend/modules/usuarios/listar_reset_logs.php

Return the 50 most recent password reset events, ordered by most recent first. Each log entry identifies both the administrator who performed the reset and the user whose password was changed. Required role: Admin (1) only

Request

No parameters required.

curl -X GET https://your-domain.com/backend/modules/usuarios/listar_reset_logs.php \
  -H "Cookie: PHPSESSID=<your_session_id>"

id_log

integer

Auto-incremented log entry identifier.

fecha_reseteo

timestamp

Timestamp when the reset was performed (Mexico City timezone).

correo_admin

string

Email of the administrator who triggered the reset.

correo_afectado

string

Email of the user whose password was reset.

id_afectado

integer

id_usuario of the affected user.

numero_cliente_afectado

string | null

Client reference number of the affected user, if assigned.

rol_afectado

string

Role name of the affected user.

Error responses

HTTP	Message
`401`	No autorizado. Inicie sesión Primero.
`403`	Acceso denegado. Permisos insuficientes.
`405`	Método no permitido
`500`	Error en el servidor: `<detail>`

GET /backend/modules/perfil/obtener.php

Retrieve the authenticated user’s own profile, including account details joined from usuarios and extended profile data from perfiles. Authentication: Any authenticated user (checkAuth)

Profile data is stored in a separate perfiles table linked by id_usuario. If the user has never saved a profile, the perfiles fields will be null in the response.

Request

No parameters. The user ID is derived from the active session ($_SESSION['id_usuario']).

curl -X GET https://your-domain.com/backend/modules/perfil/obtener.php \
  -H "Cookie: PHPSESSID=<your_session_id>"

correo

string

id_rol

integer

Numeric role ID.

nombre_rol

string

Human-readable role name.

id_perfil

integer | null

Auto-incremented primary key of the perfiles row. null if no profile row exists yet.

id_usuario

integer | null

id_usuario from the perfiles row. Matches the session user. null if no profile row exists yet.

nombre_completo

string | null

Full name of the user.

telefono

string | null

Contact phone number.

foto_perfil

string | null

Path to the profile photo file, if uploaded.

especialidad

string | null

Asesor-only field: area of specialization.

biografia

string | null

Asesor-only field: professional biography.

rfc

string | null

Cliente-only field: Mexican tax ID (RFC), up to 13 characters.

Cliente-only field: registered business name.

direccion_fiscal

string | null

Cliente-only field: fiscal address.

fecha_actualizacion

timestamp | null

Timestamp of the last profile update. null if no profile row exists yet.

Error responses

HTTP	Message
`401`	No autorizado. Inicie sesión Primero.
`403`	Cambio de contraseña obligatorio
`404`	Perfil no encontrado
`500`	Error en el servidor: `<detail>`

POST /backend/modules/perfil/actualizar.php

Create or update the authenticated user’s profile using an INSERT ... ON DUPLICATE KEY UPDATE pattern. Role-specific fields are automatically included or excluded based on the session role. Authentication: Any authenticated user (checkAuth)

You can call this endpoint even if no profile row exists yet — it will be created automatically. Subsequent calls update the existing row.

Request body

nombre_completo

string

required

Full name of the user. Maximum 255 characters.

telefono

string

Contact phone number. Maximum 20 characters.

Show Asesor-only fields (id_rol = 2)

especialidad

string

Area of tax or accounting specialization. Maximum 100 characters.

biografia

string

Professional biography text.

Show Cliente-only fields (id_rol = 3)

rfc

string

Mexican tax identifier (RFC). Maximum 13 characters.

Legal business or entity name. Maximum 255 characters.

direccion_fiscal

string

Registered fiscal address.

curl -X POST https://your-domain.com/backend/modules/perfil/actualizar.php \
  -H "Cookie: PHPSESSID=<your_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre_completo": "María García López",
    "telefono": "5512345678",
    "rfc": "GALM820315AB2",
    "razon_social": "Comercializadora García SA de CV",
    "direccion_fiscal": "Av. Insurgentes Sur 1234, CDMX"
  }'

Error responses

HTTP	Message
`400`	El nombre completo es obligatorio
`401`	No autorizado. Inicie sesión Primero.
`403`	Cambio de contraseña obligatorio
`405`	Método no permitido
`500`	Error al guardar el perfil: `<detail>`

Overview

Endpoints

Users API — Account Management and Profiles in PortalHub

Role constants

GET /backend/modules/usuarios/listar.php

Request

Response

Error responses

POST /backend/modules/usuarios/crear.php

Request body

Error responses

PUT /backend/modules/usuarios/actualizar.php

Request body

Error responses

DELETE /backend/modules/usuarios/eliminar.php

Query parameters

Error responses

POST /backend/modules/usuarios/gestionar_estado.php

Request body

Error responses

POST /backend/modules/usuarios/reset_password_admin.php

Request body

Error responses

GET /backend/modules/usuarios/listar_reset_logs.php

Request

Error responses

GET /backend/modules/perfil/obtener.php

Request

Error responses

POST /backend/modules/perfil/actualizar.php

Request body

Error responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Role constants

​GET /backend/modules/usuarios/listar.php

​Request

​Response

​Error responses

​POST /backend/modules/usuarios/crear.php

​Request body

​Error responses

​PUT /backend/modules/usuarios/actualizar.php

​Request body

​Error responses

​DELETE /backend/modules/usuarios/eliminar.php

​Query parameters

​Error responses

​POST /backend/modules/usuarios/gestionar_estado.php

​Request body

​Error responses

​POST /backend/modules/usuarios/reset_password_admin.php

​Request body

​Error responses

​GET /backend/modules/usuarios/listar_reset_logs.php

​Request

​Error responses

​GET /backend/modules/perfil/obtener.php

​Request

​Error responses

​POST /backend/modules/perfil/actualizar.php

​Request body

​Error responses

Build docs developers (and LLMs) love

Role constants

GET /backend/modules/usuarios/listar.php

Request

Response

Error responses

POST /backend/modules/usuarios/crear.php

Request body

Error responses

PUT /backend/modules/usuarios/actualizar.php

Request body

Error responses

DELETE /backend/modules/usuarios/eliminar.php

Query parameters

Error responses

POST /backend/modules/usuarios/gestionar_estado.php

Request body

Error responses

POST /backend/modules/usuarios/reset_password_admin.php

Request body

Error responses

GET /backend/modules/usuarios/listar_reset_logs.php

Request

Error responses

GET /backend/modules/perfil/obtener.php

Request

Error responses

POST /backend/modules/perfil/actualizar.php

Request body

Error responses