Authenticatie

Beveiligde Toegang tot de mindzieAPI

Leer hoe u kunt authenticeren met de mindzieAPI met Bearer tokens, beheer van tenant- en projecttoegang, en implementeer veilige API-integratiepatronen.

Overzicht Authenticatie

De mindzieAPI maakt gebruik van Bearer token authenticatie gecombineerd met tenant- en projectidentificaties om veilige, multi-tenant toegang te bieden tot mindzie resources.

Soorten API-sleutels

De mindzieAPI ondersteunt twee soorten API-sleutels met verschillende toegangsrechten:

Tenant API-sleutels (Standaard)

Tenant API-sleutels zijn gebonden aan een specifieke tenant en worden gebruikt voor de meeste API-bewerkingen:

Toegang tot projecten, datasets, onderzoeken en dashboards binnen de tenant
Uitvoeren van notebooks en blocks
Beheren van projectgebonden resources

Aanmaken via: Instellingen -> API Keys (binnen mindzieStudio)

Globale API-sleutels (Server API Keys)

Globale API-sleutels hebben systeem-brede administratieve toegang en zijn vereist voor:

Tenant API - Tenant aanmaken, opsommen, bijwerken en verwijderen
User API (Globaal) - Gebruikers aanmaken en beheren over alle tenants heen
Gebruikers toewijzen aan tenants

Aanmaken via: /admin/global-api-keys (Administrator toegang vereist)

BELANGRIJK: De Tenant API endpoints (/api/tenant) vereisen een Global API Key. Gewone tenant-specifieke API-sleutels kunnen deze endpoints niet benaderen en ontvangen een 401 Unauthorized response.

Vereiste Headers

Voor Tenant-gebonden Operaties

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

De tenant ID wordt meestal in het URL-pad opgenomen (bijv. /api/{tenantId}/project).

Voor Globale Operaties (Tenant/Gebruikersbeheer)

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Beveiligingstip: Gebruik altijd HTTPS wanneer u API-verzoeken doet om uw toegangstokens tijdens transport te beschermen.

Verkrijgen van Toegangstokens

Enterprise Server

Voor Enterprise Server implementaties, neem contact op met uw mindzie beheerder voor:

API toegangstoken
Tenant ID (GUID-formaat)
Project ID (GUID-formaat)
Basis API URL voor uw instantie

SaaS Implementatie

Voor SaaS gebruikers kunnen toegangstokens worden gegenereerd via:

mindzie Studio gebruikersinterface (Instellingen → API Keys)
Contact met uw accountbeheerder
Gebruik van authenticatie endpoints (indien ingeschakeld)

Authenticatie Testen

Gebruik de ping endpoints om uw authenticatie-instelling te verifiëren:

Basis-connectiviteitstest

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

Geauthenticeerde 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"

Succesvolle Respons

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

Beste Beveiligingspraktijken

Token Beveiliging

Bewaar tokens veilig met behulp van omgevingsvariabelen of beveiligde credential management systemen.

Token Verval

Houd tokenverval in de gaten en implementeer vernieuwingmechanismen om ononderbroken toegang te bewaren.

Multi-Tenant

Elke token is gebonden aan specifieke tenants en projecten voor veilige data-isolatie.

Implementatievoorbeelden

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("Ontbrekende vereiste omgevingsvariabelen")

    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 verzoek mislukt: {e}")

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

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

Foutafhandeling

Algemene Authenticatiefouten

Statuscode	Fout	Beschrijving	Oplossing
`401`	Unauthorized	Ongeldige of ontbrekende toegangstoken	Controleer token en zorg dat deze niet verlopen is
`403`	Forbidden	Geldige token maar onvoldoende rechten	Controleer tenant/project toegang of vraag rechten aan
`400`	Bad Request	Vereiste headers ontbreken	Zorg dat X-Tenant-Id en X-Project-Id zijn meegegeven

Voorbeeld Foutrespons

{
  "error": "invalid_token",
  "message": "De opgegeven toegangstoken is ongeldig of verlopen",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

Volgende Stappen

Zodra de authenticatie werkt, probeer dan de Quick Start Guide om uw eerste API-aanroepen te doen of verken de documentatie over Response Formats.