Authenticatie
Veilige Toegang tot de mindzieAPI
Leer hoe u zich authenticeert bij de mindzieAPI met Bearer-tokens, hoe u toegang tot tenants en projecten beheert, en hoe u veilige API-integratiepatronen implementeert.
Overzicht Authenticatie
De mindzieAPI maakt gebruik van Bearer token authenticatie in combinatie met tenant- en projectidentificaties om veilige, multi-tenant toegang tot mindzie-resources te bieden.
API-sleuteltypen
De mindzieAPI ondersteunt twee typen 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 projectniveau-resources
Aanmaken bij: Instellingen -> API Keys (binnen mindzieStudio)
Globale API-sleutels (Server API-sleutels)
Globale API-sleutels hebben systeem-brede administratieve toegang en zijn vereist voor:
- Tenant API - Aanmaken, lijst ophalen, bijwerken en verwijderen van tenants
- User API (Globaal) - Gebruikers aanmaken en beheren over alle tenants heen
- Gebruikers toewijzen aan tenants
Aanmaken bij: /admin/global-api-keys (vereist een administratieve rol: Developer, IT Admin, Administrator, of Server Administrator)
BELANGRIJK: De Tenant API endpoints (/api/tenant) vereisen een Globale API-sleutel. Gewone tenant-specifieke API-sleutels kunnen deze endpoints niet benaderen en krijgen een 401 Unauthorized fout.
Vereiste Headers
Voor Tenant-gebonden Operaties
Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json
De tenant ID wordt meestal opgenomen in het URL-pad (bijvoorbeeld /api/{tenantId}/project).
Voor Globale Operaties (Tenant-/Gebruikersbeheer)
Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json
Beveiligingsnota: Gebruik altijd HTTPS bij het maken van API-aanvragen om uw toegangstokens tijdens het transport te beschermen.
Toegangstokens Verkrijgen
Enterprise Server
Voor Enterprise Server implementaties neemt u 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-implementatie
Voor SaaS-gebruikers kunnen toegangstokens als volgt worden gegenereerd:
- Via de 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:
Basisconnectiviteitstest
Deze endpoint vereist geen authenticatie en is nuttig om te controleren of de server bereikbaar is.
curl -X GET "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/Action/unauthorized-ping"
Geauthenticeerde Test
Deze endpoint vereist een geldig Bearer-token en bevestigt dat uw token toegang heeft tot de opgegeven tenant en het project.
curl -X GET "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/Action/ping" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Geslaagde 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"]
}
Beveiligingsrichtlijnen
Tokenbeveiliging
Bewaar tokens veilig met behulp van omgevingsvariabelen of beveiligde credential-managementsystemen.
Tokenverval
Houd tokenverval in de gaten en implementeer vernieuwingmechanismen om ononderbroken toegang te behouden.
Multi-Tenant
Elk token is gebonden aan specifieke tenants en projecten voor veilige data-isolatie.
Voorbeelden Implementatie
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("Verplichte omgevingsvariabelen ontbreken")
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-aanvraag 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
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-/projecttoegang of vraag extra rechten aan |
400 |
Bad Request | Ontbrekende vereiste headers | Zorg dat X-Tenant-Id en X-Project-Id worden 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 authenticatie werkt, probeer de Quick Start Guide om uw eerste API-aanroepen te doen of verken de documentatie over Response Formats.