Usuarios, departamentos y roles

Todo esto está disponible a través de la API (/users, /departments, /roles, /permissions). La consola de administración web tiene páginas para usuarios, departamentos, roles, extensiones, dispositivos e historial; la API es la referencia completa (/api/docs).

Departamentos

Los departamentos agrupan usuarios, extensiones y dispositivos. Un rol puede asignarse a toda la empresa o a un solo departamento. Cada empresa tiene un Departamento predeterminado: puede renombrarse, pero no moverse ni eliminarse. Un usuario creado sin departamento se asigna ahí. Quien no tenga alcance en toda la empresa debe indicar el departamento explícitamente al crear un usuario.

Usuarios

La página de usuarios. La consola también se adapta a pantallas de teléfono (siguiente imagen).

La misma página en una pantalla de 390 píxeles de ancho.

• Un usuario nuevo recibe el rol integrado Usuario para toda la empresa (sus propias llamadas, buzón de voz, directorio). Cualquier otro rol se asigna con POST /users/{id}/roles.
• password al crear es opcional, se verifica contra la política de contraseñas y nunca se devuelve.
• Desactivar a un usuario termina todas sus sesiones de inmediato y bloquea el inicio de sesión.
• El restablecimiento de contraseña por un administrador (POST /users/{id}/password-reset) establece una nueva contraseña, quita cualquier bloqueo y termina las sesiones del usuario. La contraseña viaja solo en el cuerpo de la solicitud; la respuesta es 204 sin cuerpo.
• El restablecimiento de la autenticación de dos factores (POST /users/{id}/two-factor-reset) elimina el registro TOTP del usuario y termina sus sesiones.
• No puede desactivarse ni eliminarse a sí mismo (MPBX-USER-SELF), y el último Propietario de toda la empresa no puede desactivarse, eliminarse ni quedarse sin su rol (MPBX-RBAC-LAST-OWNER).

Política de contraseñas y bloqueo

Las contraseñas necesitan al menos 12 caracteres (como máximo 128) sin una combinación obligatoria de tipos de caracteres. Se rechazan las contraseñas comunes, las filas del teclado, los caracteres repetidos y el nombre o correo electrónico del propio usuario. Después de 5 inicios de sesión fallidos en 15 minutos, una cuenta se bloquea durante 15 minutos; cada bloqueo adicional seguido duplica el tiempo, hasta 1 día. Un restablecimiento de contraseña por un administrador quita el bloqueo.

Importación y exportación en CSV

GET /users/export escribe en CSV los usuarios que puede leer. POST /users/import (text/csv, como máximo 5 MiB y 2000 filas) lee el mismo formato:

email,first_name,last_name,locale,department,status,extension
ana.ruiz@acme.example,Ana,Ruiz,es-MX,Sales,active,1001

email es obligatorio. Las filas se asocian a usuarios por correo electrónico: los usuarios existentes se actualizan, los nuevos se crean, y las celdas vacías conservan los valores existentes. Las contraseñas no forman parte del archivo. La importación es una simulación de forma predeterminada (dry_run=true): el reporte muestra la acción y los errores de cada fila, y no se escribe nada. Con dry_run=false, el archivo se aplica solo si todas las filas son válidas; de lo contrario no se escribe nada y recibe 422 MPBX-IMPORT-INVALID.

Roles y permisos

Roles integrados y la cantidad de permisos que incluye cada uno.

Un permiso es una clave como queues:read. La misma clave es el ámbito de las claves de API y de cada operación de la API. Un rol es un conjunto con nombre de permisos. Un rol se asigna a un usuario para toda la empresa o para un departamento.

Existen seis roles integrados en cada empresa, de solo lectura (MPBX-RBAC-BUILTIN-READONLY): Usuario, Recepcionista, Supervisor, Administrador de departamento, Gerente y Propietario. Para cualquier otro caso, cree un rol personalizado con POST /roles a partir de la lista de permisos (GET /permissions).

Así se calculan los permisos:

• Una asignación para toda la empresa otorga los permisos del rol en toda la empresa.
• Una asignación por departamento otorga los permisos del rol con alcance de departamento solo en ese departamento. Los permisos con alcance de empresa (troncales, planes de marcación, roles) no se otorgan con una asignación de departamento.
• Los permisos se suman. Los permisos se leen de la base de datos en cada solicitud, así que un cambio de rol se aplica en la siguiente solicitud.
• Un usuario del departamento Ventas que tiene un permiso con alcance de departamento solo lista y edita los recursos de Ventas. Un recurso de otro departamento responde 403 (MPBX-RBAC-FORBIDDEN), y un recurso de otra empresa responde 404.

GET /me muestra lo que posee quien llama con la sesión iniciada y dónde.

Sin escalamiento, y quién puede cambiar a quién

• Nadie puede otorgar un permiso que no posee para ese alcance (MPBX-RBAC-ESCALATION). Un Administrador de departamento de Ventas puede asignar un rol en Ventas, no en otro departamento ni en toda la empresa.
• Actuar sobre otra cuenta (restablecer contraseña o autenticación de dos factores, desactivar, eliminar, cambiar el correo electrónico o el departamento) requiere users:write para el departamento de la cuenta y cada permiso que posee esa cuenta. Por eso, un Administrador de departamento no puede restablecer la contraseña de un Propietario que está en su departamento (MPBX-ACCOUNT-OUTRANKS).

Roles del sistema

Por encima de todas las empresas hay dos roles para toda la instalación, Administrador del sistema y Propietario del sistema. Su orden es Propietario del sistema > Administrador del sistema > ninguno. Un principal puede cambiar una cuenta que tiene un rol del sistema solo si su propio rango de sistema es estrictamente mayor, con una excepción: un Propietario del sistema puede cambiar a otro Propietario del sistema.

Actúa como	Cuenta Propietario del sistema	Cuenta Administrador del sistema	Cuenta sin rol del sistema
Propietario del sistema	sí	sí	sí
Administrador del sistema	no	no	sí
Cualquier otro (todo principal de empresa, incluido un Propietario de empresa, y toda clave de API)	no	no	sí

Las negativas son 403 MPBX-ACCOUNT-SYSTEM. El rango que cuenta es el del token utilizado: un token de ámbito de empresa o una clave de API no tiene rango de sistema, aunque su usuario tenga un rol del sistema. Un Administrador del sistema puede otorgar el rol Administrador del sistema; solo un Propietario del sistema otorga el rol Propietario del sistema, y nadie otorga un rol del sistema a sí mismo ni por encima de su propio rango. No se puede quitar al último Propietario del sistema.

Claves de API

Una clave de API la crea un usuario con la sesión iniciada que tenga api_keys:write, para sí mismo. Sus ámbitos deben ser permisos de empresa que posee quien la crea. Se envía como Authorization: Bearer mpbx_k1_... y nunca puede hacer más de lo que su propietario puede hacer en ese momento. Las claves revocadas, vencidas y desconocidas fallan todas con el mismo código (MPBX-APIKEY-INVALID).

Concurrencia optimista

PATCH y DELETE necesitan If-Match con el ETag del último GET. Si el encabezado falta, la respuesta es 428, y si está obsoleto, 412. Vea Primeros pasos con la API.