Globale Benutzeroperationen

Globale Benutzerendpunkte bieten systemweite Benutzerverwaltungsfunktionen. Diese Endpunkte erfordern einen Globalen API-Schlüssel und können Benutzer über alle Mandanten hinweg abrufen.

Authentifizierung

Alle Endpunkte auf dieser Seite erfordern einen Globalen API-Schlüssel. API-Schlüssel mit Mandantenbeschränkung erhalten einen 401 Unauthorized-Fehler.

---

Alle Benutzer auflisten

GET /api/user

Ruft eine paginierte Liste aller Benutzer über alle Mandanten hinweg ab.

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
page	integer	1	Seitenzahl für die Paginierung
pageSize	integer	50	Anzahl der Einträge pro Seite (max: 1000)
includeDisabled	boolean	false	Deaktivierte Benutzer einbeziehen
role	string	null	Nach Rollenname filtern
search	string	null	Suche nach E-Mail oder Anzeigename

Antwort (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
}

Benutzerobjekt-Felder

Feld	Typ	Beschreibung
userId	GUID	Eindeutige Benutzerkennung
email	string	E-Mail-Adresse des Benutzers (eindeutig)
displayName	string	Anzeigename des Benutzers
firstName	string	Vorname des Benutzers
lastName	string	Nachname des Benutzers
roleName	string	Rolle des Benutzers (Administrator, TenantAdmin, Analyst, etc.)
disabled	boolean	Ob das Benutzerkonto deaktiviert ist
isServiceAccount	boolean	Ob es sich um ein Servicekonto handelt
homeTenantId	GUID	Heimat-Mandant für Servicekonten
homeTenantName	string	Heimat-Mandantenname für Servicekonten
lastLogin	datetime	Letzter Login-Zeitstempel
tenantCount	integer	Anzahl der Mandanten, denen der Benutzer zugewiesen ist
tenantNames	string	Kommagetrennte Liste der Mandantennamen
dateCreated	datetime	Kontoerstellungsdatum

Fehlerantworten

Unauthorized (401):

{
  "error": "Dieser Endpunkt erfordert einen Globalen API-Schlüssel. Mandantenspezifische API-Schlüssel können nicht alle Benutzer auflisten.",
  "hint": "Verwenden Sie /api/tenant/{tenantId}/user, um Benutzer eines bestimmten Mandanten aufzulisten, oder erstellen Sie einen Globalen API-Schlüssel unter /admin/global-api-keys"
}

---

Benutzer erstellen

POST /api/user

Erstellt einen neuen Benutzer im System. Dieser wird NICHT automatisch einem Mandanten zugewiesen.

Anfragekörper

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

Anfragefelder

Feld	Typ	Erforderlich	Beschreibung
email	string	Ja	E-Mail des Benutzers (muss eindeutig sein)
displayName	string	Ja	Anzeigename (2-100 Zeichen)
firstName	string	Nein	Vorname (max. 50 Zeichen)
lastName	string	Nein	Nachname (max. 50 Zeichen)
roleName	string	Ja	Rollenname (siehe Rollen & Berechtigungen)

Antwort (201 Created)

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "message": "Benutzer erfolgreich erstellt"
}

Fehlerantworten

Conflict (409):

{
  "error": "Ein Benutzer mit der E-Mail 'john.smith@example.com' existiert bereits"
}

---

Benutzer nach ID abrufen

GET /api/user/{userId}

Ruft detaillierte Informationen für einen bestimmten Benutzer ab.

Pfadparameter

Parameter	Typ	Beschreibung
userId	GUID	Die Benutzerkennung

Antwort (200 OK)

Gibt ein vollständiges Benutzerobjekt inklusive Mandantenzuordnungen zurück.

Fehlerantworten

Not Found (404):

{
  "error": "Benutzer mit der ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' wurde nicht gefunden",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

---

Benutzer aktualisieren

PUT /api/user/{userId}

Aktualisiert Benutzerattribute. Es werden nur die angegebenen Felder aktualisiert.

Pfadparameter

Parameter	Typ	Beschreibung
userId	GUID	Die Benutzerkennung

Anfragekörper

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

Anfragefelder

Feld	Typ	Erforderlich	Beschreibung
displayName	string	Nein	Neuer Anzeigename
roleName	string	Nein	Neuer Rollenname
disabled	boolean	Nein	Konto aktivieren/deaktivieren
isServiceAccount	boolean	Nein	Servicekonto-Flag
homeTenantId	GUID	Bedingt	Erforderlich, wenn Servicekonto aktiviert wird

Regeln für Servicekonten

• Nur die Rollen Administrator und TenantAdmin können Servicekonten sein
• Bei der Ernennung zum Servicekonto ist homeTenantId erforderlich
• Bei der Aberkennung als Servicekonto wird homeTenantId automatisch gelöscht

Antwort (200 OK)

{
  "message": "Benutzer erfolgreich aktualisiert"
}

---

Benutzer nach E-Mail abrufen

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

Ruft einen Benutzer anhand seiner E-Mail-Adresse ab.

Pfadparameter

Parameter	Typ	Beschreibung
email	string	Die E-Mail-Adresse des Benutzers (URL-kodiert)

Antwort (200 OK)

Gibt ein vollständiges Benutzerobjekt zurück.

---

Gebundene Mandanten eines Benutzers abrufen

GET /api/user/{userId}/tenants

Ruft alle Mandantenzuordnungen für einen Benutzer ab.

Pfadparameter

Parameter	Typ	Beschreibung
userId	GUID	Die Benutzerkennung

Antwort (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"
    }
  ]
}

---

Implementierungsbeispiele

cURL

# Alle Benutzer auflisten (Globaler API-Schlüssel erforderlich)
curl -X GET "https://your-mindzie-instance.com/api/user?page=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# Benutzer nach Namen suchen
curl -X GET "https://your-mindzie-instance.com/api/user?search=john" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

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

# Einen neuen Benutzer erstellen
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"
  }'

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

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

# Zugeordnete Mandanten eines Benutzers abrufen
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):
        """Initialisiert mit einem GLOBALEN API-Schlüssel (nicht mandantenspezifisch)."""
        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):
        """Listet alle Benutzer über alle Mandanten hinweg auf."""
        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):
        """Erstellt einen neuen Benutzer (nicht einem Mandanten zugeordnet)."""
        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):
        """Benutzer nach ID abrufen."""
        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):
        """Benutzer anhand der E-Mail-Adresse abrufen."""
        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):
        """Benutzereigenschaften aktualisieren."""
        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):
        """Alle Mandantenzuordnungen eines Benutzers abrufen."""
        url = f'{BASE_URL}/api/user/{user_id}/tenants'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

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

# Alle Analysten auflisten
analysts = manager.list_users(role='Analyst')
print(f"Gesamtanzahl Analysten: {analysts['totalCount']}")

# Einen neuen Benutzer erstellen
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"Benutzer erstellt: {new_user['userId']}")

# Mandantenzuordnungen des Benutzers abrufen
user_id = new_user['userId']
tenants = manager.get_user_tenants(user_id)
print(f"Benutzer ist {len(tenants['tenants'])} Mandanten zugeordnet")

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(`Fehler: ${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(`Fehler: ${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(`Fehler: ${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(`Fehler: ${response.status}`);
    return await response.json();
  }
}

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

// Alle Benutzer auflisten
const users = await manager.listUsers();
console.log(`Gesamtanzahl Benutzer: ${users.totalCount}`);

// Benutzer erstellen und Mandantenzuordnungen abrufen
const newUser = await manager.createUser(
  'new@example.com',
  'New User',
  'Analyst'
);
const tenants = await manager.getUserTenants(newUser.userId);
console.log(`Zugewiesen zu ${tenants.tenants.length} Mandanten`);