Authentifizierung

Sicherer Zugriff auf die mindzieAPI

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

Überblick zur Authentifizierung

Die mindzieAPI verwendet die Bearer-Token-Authentifizierung in Kombination mit Mandanten- und Projektkennungen, um sicheren Multi-Tenant-Zugriff auf mindzie-Ressourcen zu gewährleisten.

API-Schlüsseltypen

Die mindzieAPI unterstützt zwei Typen 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 besitzen systemweite Administratorrechte und werden benötigt für:

Mandanten-API - Erstellen, Listen, Aktualisieren und Löschen von Mandanten
Benutzer-API (Global) - Erstellen und Verwalten von Benutzern in allen Mandanten
Zuweisung von Benutzern zu Mandanten

Erstellung unter: /admin/global-api-keys (Administratorzugriff erforderlich)

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

Erforderliche Header

Für Operationen mit Mandanten-Bereich

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

Die Mandanten-ID wird üblicherweise 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 für API-Anfragen, um Ihre Zugriffstokens während der Übertragung zu schützen.

Zugriffstoken erhalten

Enterprise Server

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

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

SaaS-Bereitstellung

Für SaaS-Nutzer können Zugriffstoken erzeugt werden durch:

Die Benutzeroberfläche von mindzie Studio (Einstellungen → API-Schlüssel)
Kontaktieren Ihres Account-Administrators
Nutzung der Authentifizierungsendpunkte (sofern aktiviert)

Testen der Authentifizierung

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

Grundlegender Verbindungstest

curl -X GET "https://your-mindzie-instance.com/api/Action/ping"

Authentifizierter Test

curl -X GET "https://your-mindzie-instance.com/api/Action/ping/authenticated" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID"

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

Sicherheitsrichtlinien

Sicherheit der Tokens

Speichern Sie Tokens sicher, z.B. über Umgebungsvariablen oder sichere Credential-Management-Systeme.

Token-Ablauf

Behalten Sie das Ablaufdatum der Tokens im Blick und implementieren Sie Mechanismen zur Erneuerung, um ununterbrochenen Zugriff zu gewährleisten.

Multi-Tenant

Jedes Token ist auf bestimmte Mandanten und Projekte zugeschnitten, 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}")

# Usage
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);
    }
}

// Usage
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 Zugriffstoken	Token prü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	Stellen Sie sicher, dass X-Tenant-Id und X-Project-Id angegeben sind

Beispielhafte Fehlerantwort

{
  "error": "invalid_token",
  "message": "Das bereitgestellte Zugriffstoken ist ungültig oder abgelaufen",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

Nächste Schritte

Sobald die Authentifizierung funktioniert, probieren Sie die Schnellanleitung aus, um Ihre ersten API-Aufrufe zu tätigen oder erkunden Sie die Dokumentation zu den Antwortformaten.