Roles & Permissions

User roles define access levels and capabilities within mindzieStudio. Each user is assigned a single role that determines their permissions across the platform.

When you send a roleName value to the API, use the exact strings shown in the API role name column below.

Available Roles

Role (display)	API role name	Scope	Description
Server Administrator	`TenantAdmin`	System	Highest level of access. Full reach across all tenants and the server.
Administrator	`Administrator`	Tenant	Full administrative authority within a tenant.
IT Admin	`ITAdmin`	Tenant	Integrations, connections, and global API keys.
Analyst	`Analyst`	Project	Create and manage analyses, dashboards, and investigations.
Developer	`Developer`	Project	Build integrations, manage actions and apps, view exception detail.
User	`User`	Read-only	View dashboards and analyses; cannot modify content.

Note on naming. The API role name TenantAdmin is the highest-privilege role in mindzieStudio — despite the name, it carries server-wide reach (manage all tenants, manage all users, server administration). For clarity this page also refers to it as Server Administrator. When assigning the role through the API, send TenantAdmin.

Role Details

Server Administrator (`TenantAdmin`)

The highest privilege level in mindzieStudio.

Capabilities:

Access and manage all tenants and projects
Create, modify, and delete tenants
Manage all users across the system
Open the Server Administration area (server memory, backups, executions)
Impersonate other roles for support and testing
Create Global API keys
All capabilities of every other role

Use cases:

Platform owners
Trusted operators who maintain the deployment

Administrator

Full administrative authority within a tenant, without server-wide reach.

Capabilities:

Manage users within the tenant — create, edit, deactivate, reset passwords
Assign roles within the tenant
Manage analysis templates
Manage all projects, dashboards, datasets, investigations, and apps within the tenant
Create Tenant API keys
Cannot create or delete tenants
Cannot access the Server Administration area

Use cases:

Department heads
Customer admins running their own tenant

IT Admin (`ITAdmin`)

Technical configuration access focused on integrations and data infrastructure.

Capabilities:

Configure integrations, connections, and data sources
Manage data and ETL operations
Create Global API keys
Limited authoring access — does not build dashboards or analyses

Use cases:

IT staff connecting source systems
Operators managing credentials and ETL

Analyst

Standard user role for process mining analysis.

Capabilities:

Create and manage investigations and notebooks
Upload and configure datasets
Create dashboards and reports
Execute notebooks and blocks
Manage actions and apps
Export analysis results

Use cases:

Process analysts
Data scientists
Business analysts

Developer

Access to development tools and APIs.

Capabilities:

Use development tools and platform APIs
Build custom integrations and extensions
Manage actions and apps
View exception detail for debugging
Create and manage analyses and dashboards

Use cases:

Engineers building integrations
Automation and API consumers

User

Read-only access for consuming dashboards and analyses.

Capabilities:

View shared dashboards
View published analyses
View alerts
Export visible data
Cannot modify any content

Use cases:

Executives
Stakeholders
External reviewers

Role Hierarchy

Server Administrator  (TenantAdmin)
    |
    +-- Administrator
            |
            +-- Analyst, Developer, IT Admin
                    |
                    +-- User

TenantAdmin carries the broadest reach (all tenants, server administration). Administrator has full authority within its tenant. The remaining roles are scoped to project-level or read-only work.

Service Accounts

Service accounts are special user accounts designed for API integrations and automated workflows.

Requirements

Only Server Administrator (TenantAdmin) and Administrator roles are eligible
Service accounts must have a home tenant assigned
Service accounts can authenticate via API without user login

Configuration

To promote a user to a service account:

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

To demote back to regular user:

{
  "isServiceAccount": false
}

The homeTenantId is automatically cleared when demoting.

Use Cases

CI/CD pipeline integrations
Automated data import scripts
Scheduled report generation
ETL processes
Monitoring and alerting systems

Role Assignment

When Creating Users

Specify the role in the creation request:

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

When Updating Users

Change the role with an update request:

{
  "roleName": "TenantAdmin"
}

Send the API role name exactly as listed in the table above (TenantAdmin, Administrator, ITAdmin, Analyst, Developer, or User).

API Key Types and Roles

API Key Type	Eligible Creator Roles	Access Scope
Global API Key	Server Administrator (`TenantAdmin`), IT Admin (`ITAdmin`)	All tenants, all endpoints
Tenant API Key	Server Administrator (`TenantAdmin`), Administrator, Developer	Single tenant only

Global API Key Endpoints

Only Global API keys can access:

/api/user - Global user management
/api/tenant - Tenant management
Cross-tenant operations

Tenant API Key Endpoints

Tenant API keys can access:

/api/tenant/{tenantId}/user - Tenant user management
/api/{tenantId}/project - Project operations
/api/{tenantId}/dataset - Dataset operations
All other tenant-scoped endpoints

Best Practices

Least Privilege

Assign the minimum role necessary for each user's job function.

Executive viewing dashboards     -> User
Analyst running investigations   -> Analyst
Team lead managing a tenant      -> Administrator
Platform operator managing all tenants -> Server Administrator (TenantAdmin)

Service Account Security

Create dedicated service accounts for each integration
Use descriptive display names (e.g., "CI/CD Pipeline Service")
Regularly rotate API keys
Monitor service account activity

Role Transitions

When promoting users, verify they understand new responsibilities
When demoting users, ensure they have access to complete their work
Document role changes for audit purposes

Disable vs Delete

Prefer disabling users over deleting to preserve audit trails
Disabled users cannot log in but their history is preserved
Delete only when required for data privacy

Implementation Examples

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):
        """Get all users with a specific role."""
        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):
        """Promote a user to service account."""
        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):
        """Demote a service account back to regular user."""
        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):
        """Change a user's role. Use API role names: 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):
        """Disable a user account."""
        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()

# Usage
manager = RoleManager('your-global-api-key')

# List all server administrators (TenantAdmin role)
server_admins = manager.get_users_by_role('TenantAdmin')
print(f"System has {server_admins['totalCount']} server administrators")

# Promote user to service account
manager.promote_to_service_account(
    user_id='a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    home_tenant_id='12345678-1234-1234-1234-123456789012'
)

# Promote an Analyst to Server Administrator
manager.change_role(
    user_id='a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    new_role='TenantAdmin'
)

# Disable a user instead of deleting
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) {
    // Use API role names: 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();
  }
}

// Usage
const manager = new RoleManager('your-global-api-key');

// Get all analysts
const analysts = await manager.getUsersByRole('Analyst');
console.log(`${analysts.totalCount} analysts in system`);

// Promote to Server Administrator
await manager.changeRole('user-id', 'TenantAdmin');

Roles & Permissions

Available Roles

Role Details

Server Administrator (TenantAdmin)

Administrator

IT Admin (ITAdmin)

Analyst

Developer

User

Role Hierarchy

Service Accounts

Requirements

Configuration

Use Cases

Role Assignment

When Creating Users

When Updating Users

API Key Types and Roles

Global API Key Endpoints

Tenant API Key Endpoints

Best Practices

Least Privilege

Service Account Security

Role Transitions

Disable vs Delete

Implementation Examples

Python

JavaScript

Server Administrator (`TenantAdmin`)

IT Admin (`ITAdmin`)