Authenticatie

Veilige Toegang tot de mindzieAPI

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

Overzicht Authenticatie

De mindzieAPI gebruikt Bearer token authenticatie gecombineerd met tenant- en projectidentificatoren om veilige, multi-tenant toegang tot mindzie resources te bieden.

API Sleuteltypen

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

Tenant API-sleutels (Standaard)

Tenant API-sleutels zijn beperkt tot een specifieke tenant en worden gebruikt voor de meeste API-acties:

Toegang tot projecten, datasets, onderzoeken en dashboards binnen de tenant
Notebooks en blocks uitvoeren
Beheer van projectniveau 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 - Tenants aanmaken, weergeven, bijwerken en verwijderen
User API (Globaal) - Gebruikers aanmaken en beheren over alle tenants heen
Gebruikers toewijzen aan tenants

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

BELANGRIJK: De Tenant API endpoints (/api/tenant) vereisen een Global API Key. Gewone tenant-specifieke API-sleutels hebben geen toegang tot deze endpoints en krijgen een 401 Unauthorized respons.

Vereiste Headers

Voor Tenant-Gebonden Acties

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

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

Voor Global Acties (Tenant-/Gebruikersbeheer)

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Beveiligingsopmerking: Gebruik altijd HTTPS bij API-aanvragen om uw toegangstokens tijdens verzending te beschermen.

Toegangstokens Verkrijgen

Enterprise Server

Voor Enterprise Server implementaties, neem contact op met uw mindzie beheerder om te verkrijgen:

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

SaaS Deployment

Voor SaaS-gebruikers kunnen toegangstokens worden gegenereerd via:

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

Authenticatie Testen

Gebruik de ping endpoints om uw authenticatie-instellingen 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"]
}

Beveiligingsbest practices

Token Beveiliging

Bewaar tokens veilig via omgevingsvariabelen of beveiligde credential management systemen.

Token Verloop

Houd token verloop in de gaten en implementeer vernieuwingmechanismen om ononderbroken toegang te waarborgen.

Multi-Tenant

Elk token is beperkt tot 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("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")
);

Foutafhandeling

Veelvoorkomende Authenticatiefouten

Statuscode	Fout	Beschrijving	Oplossing
`401`	Unauthorized	Ongeldig of ontbrekend 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	Ontbrekende vereiste headers	Zorg dat X-Tenant-Id en X-Project-Id zijn meegegeven

Voorbeeld Foutrespons

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

Volgende Stappen

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