Authentifizierung

Sicherer Zugriff auf die mindzieAPI

Erfahren Sie, wie Sie sich mit der mindzieAPI unter Verwendung von Bearer Tokens authentifizieren, den Zugriff auf Mandanten und Projekte verwalten und sichere API-Integrationsmuster implementieren.

Übersicht zur Authentifizierung

Die mindzieAPI verwendet die Authentifizierung mit Bearer Tokens kombiniert mit Mandanten- und Projektkennungen, um sicheren Multi-Tenant-Zugriff auf mindzie-Ressourcen zu ermöglichen.

API-Schlüsseltypen

Die mindzieAPI unterstützt zwei Arten von API-Schlüsseln mit unterschiedlichen Zugriffsebenen:

Mandanten-API-Schlüssel (Standard)

Mandanten-API-Schlüssel sind auf einen bestimmten Mandanten beschränkt und werden für die meisten API-Operationen verwendet:

Zugriff auf Projekte, Datensätze, Untersuchungen und Dashboards innerhalb des Mandanten
Ausführung von Notebooks und Blöcken
Verwaltung von Ressourcen auf Projektebene

Erstellung unter: Einstellungen -> API-Schlüssel (innerhalb von mindzieStudio)

Globale API-Schlüssel (Server-API-Schlüssel)

Globale API-Schlüssel verfügen über systemweite administrative Zugriffsrechte und werden benötigt für:

Tenant API – Erstellen, Auflisten, Aktualisieren und Löschen von Mandanten
User API (Global) – Erstellen und Verwalten von Benutzern über alle Mandanten hinweg
Zuweisung von Benutzern zu Mandanten

Erstellung unter: /admin/global-api-keys (erfordert eine administrative Rolle: Developer, IT Admin, Administrator oder Server Administrator)

WICHTIG: Die Tenant API-Endpunkte (/api/tenant) erfordern einen Globalen API-Schlüssel. Reguläre mandantenspezifische API-Schlüssel können auf diese Endpunkte nicht zugreifen und erhalten eine 401 Unauthorized-Antwort.

Erforderliche Header

Für mandantenspezifische Operationen

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

Die Mandanten-ID wird typischerweise im URL-Pfad angegeben (z.B. /api/{tenantId}/project).

Für globale Operationen (Mandanten-/Benutzerverwaltung)

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Sicherheitshinweis: Verwenden Sie immer HTTPS bei API-Anfragen, um Ihre Zugangstoken während der Übertragung zu schützen.

Zugangstoken erhalten

Enterprise Server

Für Enterprise-Server-Installationen kontaktieren Sie Ihren mindzie-Administrator, um zu erhalten:

API-Zugangstoken
Mandanten-ID (im GUID-Format)
Projekt-ID (im GUID-Format)
Basis-API-URL für Ihre Instanz

SaaS-Bereitstellung

Für SaaS-Nutzer können Zugangstoken generiert werden über:

die Benutzeroberfläche von mindzie Studio (Einstellungen → API-Schlüssel)
Kontaktaufnahme mit Ihrem Kontoadministrator
Verwendung der Authentifizierungsendpunkte (falls aktiviert)

Authentifizierung testen

Verwenden Sie die Ping-Endpunkte, um Ihre Authentifizierung zu überprüfen:

Grundlegender Verbindungstest

Dieser Endpunkt erfordert keine Authentifizierung und dient dazu zu prüfen, ob der Server erreichbar ist.

curl -X GET "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/Action/unauthorized-ping"

Authentifizierter Test

Dieser Endpunkt erfordert ein gültiges Bearer-Token und bestätigt, dass Ihr Token Zugriff auf den angegebenen Mandanten und das Projekt hat.

curl -X GET "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/Action/ping" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Erfolgreiche Antwort

{
  "status": "authenticated",
  "timestamp": "2024-01-15T10:30:00Z",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "projectId": "87654321-4321-4321-4321-210987654321",
  "userId": "user@company.com",
  "permissions": ["read", "write", "admin"]
}

Sicherheits-Best-Practices

Token-Sicherheit

Speichern Sie Tokens sicher, z.B. in Umgebungsvariablen oder sicheren Credential-Management-Systemen.

Token-Ablauf

Überwachen Sie das Ablaufdatum der Tokens und implementieren Sie Mechanismen zur Token-Aktualisierung, um unterbrechungsfreien Zugriff zu gewährleisten.

Multi-Tenant

Jedes Token ist auf bestimmte Mandanten und Projekte beschränkt, um eine sichere Datenisolation zu gewährleisten.

Implementierungsbeispiele

JavaScript/Node.js

const apiConfig = {
  baseURL: process.env.MINDZIE_API_URL,
  token: process.env.MINDZIE_ACCESS_TOKEN,
  tenantId: process.env.MINDZIE_TENANT_ID,
  projectId: process.env.MINDZIE_PROJECT_ID
};

const makeAuthenticatedRequest = async (endpoint, options = {}) => {
  const url = `${apiConfig.baseURL}${endpoint}`;
  const headers = {
    'Authorization': `Bearer ${apiConfig.token}`,
    'X-Tenant-Id': apiConfig.tenantId,
    'X-Project-Id': apiConfig.projectId,
    'Content-Type': 'application/json',
    ...options.headers
  };

  try {
    const response = await fetch(url, {
      ...options,
      headers
    });

    if (!response.ok) {
      throw new Error(`API request failed: ${response.status} ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API request error:', error);
    throw error;
  }
};

Python

import os
import requests
from typing import Dict, Any

class MindzieAPIClient:
    def __init__(self):
        self.base_url = os.getenv('MINDZIE_API_URL')
        self.token = os.getenv('MINDZIE_ACCESS_TOKEN')
        self.tenant_id = os.getenv('MINDZIE_TENANT_ID')
        self.project_id = os.getenv('MINDZIE_PROJECT_ID')

        if not all([self.base_url, self.token, self.tenant_id, self.project_id]):
            raise ValueError("Missing required environment variables")

    def _get_headers(self) -> Dict[str, str]:
        return {
            'Authorization': f'Bearer {self.token}',
            'X-Tenant-Id': self.tenant_id,
            'X-Project-Id': self.project_id,
            'Content-Type': 'application/json'
        }

    def make_request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
        url = f"{self.base_url.rstrip('/')}{endpoint}"
        headers = self._get_headers()

        if 'headers' in kwargs:
            headers.update(kwargs['headers'])

        kwargs['headers'] = headers

        try:
            response = requests.request(method, url, **kwargs)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            raise Exception(f"API request failed: {e}")

# Verwendung
client = MindzieAPIClient()
result = client.make_request('GET', '/api/Action/ping/authenticated')

C#/.NET

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

public class MindzieApiClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly string _tenantId;
    private readonly string _projectId;

    public MindzieApiClient(string baseUrl, string accessToken, string tenantId, string projectId)
    {
        _baseUrl = baseUrl.TrimEnd('/');
        _tenantId = tenantId;
        _projectId = projectId;

        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
        _httpClient.DefaultRequestHeaders.Add("X-Tenant-Id", tenantId);
        _httpClient.DefaultRequestHeaders.Add("X-Project-Id", projectId);
    }

    public async Task<T> GetAsync<T>(string endpoint)
    {
        var response = await _httpClient.GetAsync($"{_baseUrl}{endpoint}");
        response.EnsureSuccessStatusCode();

        var content = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<T>(content);
    }

    public async Task<T> PostAsync<T>(string endpoint, object data)
    {
        var json = JsonSerializer.Serialize(data);
        var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

        var response = await _httpClient.PostAsync($"{_baseUrl}{endpoint}", content);
        response.EnsureSuccessStatusCode();

        var responseContent = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<T>(responseContent);
    }
}

// Verwendung
var client = new MindzieApiClient(
    Environment.GetEnvironmentVariable("MINDZIE_API_URL"),
    Environment.GetEnvironmentVariable("MINDZIE_ACCESS_TOKEN"),
    Environment.GetEnvironmentVariable("MINDZIE_TENANT_ID"),
    Environment.GetEnvironmentVariable("MINDZIE_PROJECT_ID")
);

Fehlerbehandlung

Häufige Authentifizierungsfehler

Statuscode	Fehler	Beschreibung	Lösung
`401`	Unauthorized	Ungültiges oder fehlendes Token	Token überprüfen und sicherstellen, dass es nicht abgelaufen ist
`403`	Forbidden	Gültiges Token, aber unzureichende Berechtigungen	Mandanten-/Projektzugriff prüfen oder Berechtigungen anfordern
`400`	Bad Request	Fehlende erforderliche Header	Überprüfen, ob X-Tenant-Id und X-Project-Id gesetzt sind

Beispiel für eine Fehlerantwort

{
  "error": "invalid_token",
  "message": "The provided access token is invalid or expired",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

Nächste Schritte

Sobald die Authentifizierung funktioniert, probieren Sie die Schnellstartanleitung aus, um erste API-Aufrufe zu tätigen, oder erkunden Sie die Dokumentation zu Antwortformaten.