Roles y Permisos

Los roles de usuario definen los niveles de acceso y capacidades dentro de mindzieStudio. A cada usuario se le asigna un solo rol que determina sus permisos en toda la plataforma.

Cuando envíes un valor roleName a la API, usa las cadenas exactas mostradas en la columna API role name a continuación.

Roles Disponibles

Rol (mostrar)	API role name	Alcance	Descripción
Administrador del Servidor	`TenantAdmin`	Sistema	Nivel más alto de acceso. Alcance total en todos los tenants y el servidor.
Administrador	`Administrator`	Tenant	Autoridad administrativa completa dentro de un tenant.
Administrador IT	`ITAdmin`	Tenant	Integraciones, conexiones y claves API globales.
Analista	`Analyst`	Proyecto	Crear y gestionar análisis, dashboards e investigaciones.
Desarrollador	`Developer`	Proyecto	Construir integraciones, manejar acciones y apps, ver detalles de excepciones.
Usuario	`User`	Solo lectura	Ver dashboards y análisis; no puede modificar contenido.

Nota sobre la nomenclatura. El nombre de rol API TenantAdmin es el rol con privilegios más altos en mindzieStudio — a pesar del nombre, tiene alcance en todo el servidor (administra todos los tenants, todos los usuarios, administración del servidor). Para mayor claridad, esta página también lo denomina Administrador del Servidor. Al asignar el rol mediante la API, envíe TenantAdmin.

Detalles del Rol

Administrador del Servidor (`TenantAdmin`)

El nivel de privilegio más alto en mindzieStudio.

Capacidades:

Acceder y administrar todos los tenants y proyectos
Crear, modificar y eliminar tenants
Gestionar todos los usuarios en el sistema
Abrir el área de Administración del Servidor (memoria del servidor, respaldos, ejecuciones)
Suplantar otros roles para soporte y pruebas
Crear claves API Globales
Todas las capacidades de los demás roles

Casos de uso:

Propietarios de la plataforma
Operadores de confianza que mantienen el despliegue

Administrador

Autoridad administrativa completa dentro de un tenant, sin alcance en todo el servidor.

Capacidades:

Gestionar usuarios dentro del tenant — crear, editar, desactivar, restablecer contraseñas
Asignar roles dentro del tenant
Gestionar plantillas de análisis
Gestionar todos los proyectos, dashboards, conjuntos de datos, investigaciones y apps dentro del tenant
Crear claves API de Tenant
No puede crear ni eliminar tenants
No puede acceder al área de Administración del Servidor

Casos de uso:

Jefes de departamento
Administradores de clientes que manejan su propio tenant

Administrador IT (`ITAdmin`)

Acceso de configuración técnica enfocado en integraciones e infraestructura de datos.

Capacidades:

Configurar integraciones, conexiones y fuentes de datos
Gestionar datos y operaciones ETL
Crear claves API Globales
Acceso limitado a autoría — no construye dashboards ni análisis

Casos de uso:

Personal de IT conectando sistemas fuente
Operadores que gestionan credenciales y ETL

Analista

Rol estándar para análisis de minería de procesos.

Capacidades:

Crear y gestionar investigaciones y notebooks
Subir y configurar conjuntos de datos
Crear dashboards e informes
Ejecutar notebooks y bloques
Gestionar acciones y apps
Exportar resultados de análisis

Casos de uso:

Analistas de procesos
Científicos de datos
Analistas de negocio

Desarrollador

Acceso a herramientas de desarrollo y APIs.

Capacidades:

Usar herramientas de desarrollo y APIs de la plataforma
Construir integraciones y extensiones personalizadas
Gestionar acciones y apps
Ver detalles de excepciones para depuración
Crear y gestionar análisis y dashboards

Casos de uso:

Ingenieros que construyen integraciones
Consumidores de automatización y APIs

Usuario

Acceso solo lectura para consumir dashboards y análisis.

Capacidades:

Ver dashboards compartidos
Ver análisis publicados
Ver alertas
Exportar datos visibles
No puede modificar ningún contenido

Casos de uso:

Ejecutivos
Partes interesadas
Revisores externos

Jerarquía de Roles

Administrador del Servidor  (TenantAdmin)
    |
    +-- Administrador
            |
            +-- Analista, Desarrollador, Administrador IT
                    |
                    +-- Usuario

TenantAdmin tiene el alcance más amplio (todos los tenants, administración del servidor). Administrator tiene autoridad completa dentro de su tenant. Los roles restantes tienen alcance a nivel de proyecto o solo lectura.

Cuentas de Servicio

Las cuentas de servicio son cuentas de usuario especiales diseñadas para integraciones API y flujos de trabajo automatizados.

Requisitos

Solo los roles Administrador del Servidor (TenantAdmin) y Administrador son elegibles
Las cuentas de servicio deben tener un tenant principal asignado
Las cuentas de servicio pueden autenticarse vía API sin inicio de sesión de usuario

Configuración

Para promover un usuario a cuenta de servicio:

{
  "isServiceAccount": true,
  "homeTenantId": "12345678-1234-1234-1234-123456789012"
}

Para degradar a usuario regular:

{
  "isServiceAccount": false
}

El homeTenantId se elimina automáticamente al degradar.

Casos de uso

Integraciones de pipelines CI/CD
Scripts automatizados de importación de datos
Generación programada de reportes
Procesos ETL
Sistemas de monitoreo y alertas

Asignación de Roles

Al Crear Usuarios

Especificar el rol en la solicitud de creación:

{
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "roleName": "Analyst"
}

Al Actualizar Usuarios

Cambiar el rol con una solicitud de actualización:

{
  "roleName": "TenantAdmin"
}

Envía el nombre de rol API exactamente como aparece en la tabla arriba (TenantAdmin, Administrator, ITAdmin, Analyst, Developer o User).

Tipos de Claves API y Roles

Tipo de Clave API	Roles elegibles para creación	Alcance de acceso
Clave API Global	Administrador del Servidor (`TenantAdmin`), Administrador IT (`ITAdmin`)	Todos los tenants, todos los endpoints
Clave API de Tenant	Administrador del Servidor (`TenantAdmin`), Administrador, Desarrollador	Solo un tenant

Endpoints de Claves API Globales

Solo las claves API globales pueden acceder a:

/api/user - Gestión global de usuarios
/api/tenant - Gestión de tenants
Operaciones entre tenants

Endpoints de Claves API de Tenant

Las claves API de tenant pueden acceder a:

/api/tenant/{tenantId}/user - Gestión de usuarios del tenant
/api/{tenantId}/project - Operaciones de proyecto
/api/{tenantId}/dataset - Operaciones de conjunto de datos
Todos los demás endpoints con alcance tenant

Mejores Prácticas

Menor Privilegio

Asigna el rol mínimo necesario para la función laboral de cada usuario.

Ejecutivo que ve dashboards      -> Usuario
Analista que ejecuta investigaciones -> Analista
Líder de equipo que administra un tenant -> Administrador
Operador de plataforma que maneja todos los tenants -> Administrador del Servidor (TenantAdmin)

Seguridad de la Cuenta de Servicio

Crear cuentas de servicio dedicadas para cada integración
Usar nombres descriptivos para mostrar (ej., "Servicio de Pipeline CI/CD")
Rotar regularmente las claves API
Monitorear la actividad de las cuentas de servicio

Transiciones de Roles

Al promover usuarios, verificar que comprendan sus nuevas responsabilidades
Al degradar usuarios, asegurar que tengan acceso para completar su trabajo
Documentar cambios de rol para auditoría

Deshabilitar vs Eliminar

Prefiere deshabilitar usuarios en vez de eliminarlos para preservar el historial de auditoría
Los usuarios deshabilitados no pueden iniciar sesión pero su historial se conserva
Eliminar solo cuando es necesario por razones de privacidad de datos

Ejemplos de Implementación

Python

import requests

BASE_URL = 'https://your-mindzie-instance.com'

class RoleManager:
    def __init__(self, global_api_key):
        self.headers = {
            'Authorization': f'Bearer {global_api_key}',
            'Content-Type': 'application/json'
        }

    def get_users_by_role(self, role_name):
        """Obtener todos los usuarios con un rol específico."""
        url = f'{BASE_URL}/api/user'
        params = {'role': role_name, 'pageSize': 1000}
        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def promote_to_service_account(self, user_id, home_tenant_id):
        """Promover a un usuario a cuenta de servicio."""
        url = f'{BASE_URL}/api/user/{user_id}'
        payload = {
            'isServiceAccount': True,
            'homeTenantId': home_tenant_id
        }
        response = requests.put(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def demote_from_service_account(self, user_id):
        """Degradar una cuenta de servicio a usuario regular."""
        url = f'{BASE_URL}/api/user/{user_id}'
        payload = {'isServiceAccount': False}
        response = requests.put(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def change_role(self, user_id, new_role):
        """Cambiar el rol de un usuario. Usa los nombres de rol API: TenantAdmin, Administrator, ITAdmin, Analyst, Developer, User."""
        url = f'{BASE_URL}/api/user/{user_id}'
        payload = {'roleName': new_role}
        response = requests.put(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def disable_user(self, user_id):
        """Deshabilitar una cuenta de usuario."""
        url = f'{BASE_URL}/api/user/{user_id}'
        payload = {'disabled': True}
        response = requests.put(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

# Uso
manager = RoleManager('tu-clave-api-global')

# Listar todos los administradores del servidor (rol TenantAdmin)
server_admins = manager.get_users_by_role('TenantAdmin')
print(f"El sistema tiene {server_admins['totalCount']} administradores del servidor")

# Promover usuario a cuenta de servicio
manager.promote_to_service_account(
    user_id='a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    home_tenant_id='12345678-1234-1234-1234-123456789012'
)

# Promover un Analista a Administrador del Servidor
manager.change_role(
    user_id='a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    new_role='TenantAdmin'
)

# Deshabilitar un usuario en lugar de eliminarlo
manager.disable_user('departing-user-id')

JavaScript

class RoleManager {
  constructor(globalApiKey) {
    this.headers = {
      'Authorization': `Bearer ${globalApiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async getUsersByRole(roleName) {
    const url = `${BASE_URL}/api/user?role=${roleName}&pageSize=1000`;
    const response = await fetch(url, { headers: this.headers });
    return await response.json();
  }

  async promoteToServiceAccount(userId, homeTenantId) {
    const url = `${BASE_URL}/api/user/${userId}`;
    const response = await fetch(url, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify({
        isServiceAccount: true,
        homeTenantId
      })
    });
    return await response.json();
  }

  async changeRole(userId, newRole) {
    // Usa nombres de rol API: TenantAdmin, Administrator, ITAdmin, Analyst, Developer, User
    const url = `${BASE_URL}/api/user/${userId}`;
    const response = await fetch(url, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify({ roleName: newRole })
    });
    return await response.json();
  }
}

// Uso
const manager = new RoleManager('tu-clave-api-global');

// Obtener todos los analistas
const analysts = await manager.getUsersByRole('Analyst');
console.log(`${analysts.totalCount} analistas en el sistema`);

// Promover a Administrador del Servidor
await manager.changeRole('user-id', 'TenantAdmin');

Roles y Permisos

Roles Disponibles

Detalles del Rol

Administrador del Servidor (TenantAdmin)

Administrador

Administrador IT (ITAdmin)

Analista

Desarrollador

Usuario

Jerarquía de Roles

Cuentas de Servicio

Requisitos

Configuración

Casos de uso

Asignación de Roles

Al Crear Usuarios

Al Actualizar Usuarios

Tipos de Claves API y Roles

Endpoints de Claves API Globales

Endpoints de Claves API de Tenant

Mejores Prácticas

Menor Privilegio

Seguridad de la Cuenta de Servicio

Transiciones de Roles

Deshabilitar vs Eliminar

Ejemplos de Implementación

Python

JavaScript

Administrador del Servidor (`TenantAdmin`)

Administrador IT (`ITAdmin`)