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.

Überblick zur Authentifizierung

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

Arten von API-Schlüsseln

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ühren von Notebooks und Blöcken
Verwalten von Ressourcen auf Projektebene

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

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

Globale API-Schlüssel haben systemweite Administratorrechte und sind erforderlich für:

Mandanten-API - Erstellen, Auflisten, Aktualisieren und Löschen von Mandanten
Benutzer-API (global) - Erstellen und Verwalten von Benutzern über alle Mandanten hinweg
Benutzer Mandanten zuweisen

Erstellen unter: /admin/global-api-keys (Administratorzugang 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 mandantenbezogene Operationen

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

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

Für globale Operationen (Mandanten-/Benutzerverwaltung)

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

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

Zugangstoken erhalten

Enterprise Server

Für Enterprise-Server-Installationen wenden Sie sich an 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 erzeugt werden über:

Benutzeroberfläche von mindzie Studio (Einstellungen → API-Schlüssel)
Kontaktieren des Kontoadministrators
Nutzung der Authentifizierungsendpunkte (sofern aktiviert)

Authentifizierung testen

Verwenden Sie die Ping-Endpunkte, um Ihre Authentifizierung einzurichten und zu prü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"]
}

Sicherheits-Best Practices

Token-Sicherheit

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

Token-Ablauf

Beobachten Sie das Ablaufdatum von Tokens und implementieren Sie Erneuerungsmechanismen, um unterbrechungsfreien Zugang sicherzustellen.

Multi-Tenant

Jedes Token ist gezielt für bestimmte Mandanten und Projekte ausgelegt, 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	Zugriff auf Mandant/Projekt überprüfen oder Berechtigungen anfordern
`400`	Bad Request	Fehlende erforderliche Header	Stellen Sie sicher, dass X-Tenant-Id und X-Project-Id bereitgestellt werden

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 Ihre ersten API-Aufrufe zu tätigen, oder erkunden Sie die Dokumentation zu Antwortformaten.