Global User Operations

Global user endpoints provide system-wide user management capabilities. These endpoints require a Global API Key and can access users across all tenants.

Authentication

All endpoints on this page require a Global API Key. Tenant-scoped API keys will receive a 401 Unauthorized error.

---

List All Users

GET /api/user

Retrieves a paginated list of all users across all tenants.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number for pagination
pageSize	integer	50	Number of items per page (max: 1000)
includeDisabled	boolean	false	Include disabled users
role	string	null	Filter by role name
search	string	null	Search by email or display name

Response (200 OK)

{
  "users": [
    {
      "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "john.smith@example.com",
      "displayName": "John Smith",
      "firstName": "John",
      "lastName": "Smith",
      "roleName": "Analyst",
      "disabled": false,
      "isServiceAccount": false,
      "homeTenantId": null,
      "homeTenantName": null,
      "lastLogin": "2024-01-15T10:30:00Z",
      "tenantCount": 2,
      "tenantNames": "acme-corp, globex-inc",
      "dateCreated": "2024-01-01T00:00:00Z"
    }
  ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 50
}

User Object Fields

Field	Type	Description
userId	GUID	Unique identifier for the user
email	string	User's email address (unique)
displayName	string	User's display name
firstName	string	User's first name
lastName	string	User's last name
roleName	string	User's role (Administrator, TenantAdmin, Analyst, etc.)
disabled	boolean	Whether the user account is disabled
isServiceAccount	boolean	Whether this is a service account
homeTenantId	GUID	Home tenant for service accounts
homeTenantName	string	Home tenant name for service accounts
lastLogin	datetime	Last login timestamp
tenantCount	integer	Number of tenants user is assigned to
tenantNames	string	Comma-separated list of tenant names
dateCreated	datetime	Account creation date

Error Responses

Unauthorized (401):

{
  "error": "This endpoint requires a Global API key. Tenant-specific API keys cannot list all users.",
  "hint": "Use /api/tenant/{tenantId}/user to list users for a specific tenant, or create a Global API key at /admin/global-api-keys"
}

---

Create User

POST /api/user

Creates a new user in the system. This does NOT assign the user to any tenants.

Request Body

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

Request Fields

Field	Type	Required	Description
email	string	Yes	User's email (must be unique)
displayName	string	Yes	Display name (2-100 characters)
firstName	string	No	First name (max 50 characters)
lastName	string	No	Last name (max 50 characters)
roleName	string	Yes	Role name (see Roles & Permissions)

Response (201 Created)

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "message": "User created successfully"
}

Error Responses

Conflict (409):

{
  "error": "A user with email 'john.smith@example.com' already exists"
}

---

Get User by ID

GET /api/user/{userId}

Retrieves detailed information for a specific user.

Path Parameters

Parameter	Type	Description
userId	GUID	The user identifier

Response (200 OK)

Returns a full user object with tenant assignments.

Error Responses

Not Found (404):

{
  "error": "User not found with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

---

Update User

PUT /api/user/{userId}

Updates user properties. Only provided fields will be updated.

Path Parameters

Parameter	Type	Description
userId	GUID	The user identifier

Request Body

{
  "displayName": "Jane Smith",
  "roleName": "TenantAdmin",
  "disabled": false,
  "isServiceAccount": true,
  "homeTenantId": "12345678-1234-1234-1234-123456789012"
}

Request Fields

Field	Type	Required	Description
displayName	string	No	New display name
roleName	string	No	New role name
disabled	boolean	No	Enable/disable account
isServiceAccount	boolean	No	Service account flag
homeTenantId	GUID	Conditional	Required if making service account

Service Account Rules

• Only Administrator and TenantAdmin roles can be service accounts
• When promoting to service account, homeTenantId is required
• When demoting from service account, homeTenantId is automatically cleared

Response (200 OK)

{
  "message": "User updated successfully"
}

---

Get User by Email

GET /api/user/by-email/{email}

Retrieves a user by their email address.

Path Parameters

Parameter	Type	Description
email	string	The user's email address (URL encoded)

Response (200 OK)

Returns a full user object.

---

Get User's Tenants

GET /api/user/{userId}/tenants

Retrieves all tenant assignments for a user.

Path Parameters

Parameter	Type	Description
userId	GUID	The user identifier

Response (200 OK)

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "tenants": [
    {
      "tenantId": "12345678-1234-1234-1234-123456789012",
      "tenantName": "acme-corp",
      "displayName": "Acme Corporation",
      "dateAssigned": "2024-01-15T10:30:00Z"
    }
  ]
}

---

Implementation Examples

cURL

# List all users (Global API key required)
curl -X GET "https://your-mindzie-instance.com/api/user?page=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Search for users by name
curl -X GET "https://your-mindzie-instance.com/api/user?search=john" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Filter by role
curl -X GET "https://your-mindzie-instance.com/api/user?role=Analyst" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Create a new user
curl -X POST "https://your-mindzie-instance.com/api/user" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.smith@example.com",
    "displayName": "John Smith",
    "roleName": "Analyst"
  }'

# Get user by ID
curl -X GET "https://your-mindzie-instance.com/api/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Get user by email
curl -X GET "https://your-mindzie-instance.com/api/user/by-email/john.smith%40example.com" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Get user's tenants
curl -X GET "https://your-mindzie-instance.com/api/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890/tenants" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

Python

import requests

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

class GlobalUserManager:
    def __init__(self, global_api_key):
        """Initialize with a GLOBAL API key (not tenant-specific)."""
        self.headers = {
            'Authorization': f'Bearer {global_api_key}',
            'Content-Type': 'application/json'
        }

    def list_users(self, page=1, page_size=50, include_disabled=False,
                   role=None, search=None):
        """List all users across all tenants."""
        url = f'{BASE_URL}/api/user'
        params = {
            'page': page,
            'pageSize': page_size,
            'includeDisabled': include_disabled
        }
        if role:
            params['role'] = role
        if search:
            params['search'] = search

        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def create_user(self, email, display_name, role_name,
                    first_name=None, last_name=None):
        """Create a new user (not assigned to any tenant)."""
        url = f'{BASE_URL}/api/user'
        payload = {
            'email': email,
            'displayName': display_name,
            'roleName': role_name
        }
        if first_name:
            payload['firstName'] = first_name
        if last_name:
            payload['lastName'] = last_name

        response = requests.post(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_user(self, user_id):
        """Get user by ID."""
        url = f'{BASE_URL}/api/user/{user_id}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_user_by_email(self, email):
        """Get user by email address."""
        from urllib.parse import quote
        url = f'{BASE_URL}/api/user/by-email/{quote(email, safe="")}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def update_user(self, user_id, display_name=None, role_name=None,
                    disabled=None, is_service_account=None, home_tenant_id=None):
        """Update user properties."""
        url = f'{BASE_URL}/api/user/{user_id}'
        payload = {}
        if display_name is not None:
            payload['displayName'] = display_name
        if role_name is not None:
            payload['roleName'] = role_name
        if disabled is not None:
            payload['disabled'] = disabled
        if is_service_account is not None:
            payload['isServiceAccount'] = is_service_account
        if home_tenant_id is not None:
            payload['homeTenantId'] = home_tenant_id

        response = requests.put(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_user_tenants(self, user_id):
        """Get all tenant assignments for a user."""
        url = f'{BASE_URL}/api/user/{user_id}/tenants'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

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

# List all analysts
analysts = manager.list_users(role='Analyst')
print(f"Total analysts: {analysts['totalCount']}")

# Create a new user
new_user = manager.create_user(
    email='new.analyst@example.com',
    display_name='New Analyst',
    role_name='Analyst',
    first_name='New',
    last_name='Analyst'
)
print(f"Created user: {new_user['userId']}")

# Get user's tenant assignments
user_id = new_user['userId']
tenants = manager.get_user_tenants(user_id)
print(f"User is assigned to {len(tenants['tenants'])} tenants")

JavaScript/Node.js

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

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

  async listUsers(options = {}) {
    const params = new URLSearchParams({
      page: options.page || 1,
      pageSize: options.pageSize || 50,
      includeDisabled: options.includeDisabled || false
    });
    if (options.role) params.append('role', options.role);
    if (options.search) params.append('search', options.search);

    const url = `${BASE_URL}/api/user?${params}`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async createUser(email, displayName, roleName) {
    const url = `${BASE_URL}/api/user`;
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ email, displayName, roleName })
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async getUser(userId) {
    const url = `${BASE_URL}/api/user/${userId}`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async getUserTenants(userId) {
    const url = `${BASE_URL}/api/user/${userId}/tenants`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }
}

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

// List all users
const users = await manager.listUsers();
console.log(`Total users: ${users.totalCount}`);

// Create and check tenant assignments
const newUser = await manager.createUser(
  'new@example.com',
  'New User',
  'Analyst'
);
const tenants = await manager.getUserTenants(newUser.userId);
console.log(`Assigned to ${tenants.tenants.length} tenants`);