Authentification

Accès sécurisé à mindzieAPI

Apprenez comment vous authentifier avec mindzieAPI en utilisant des tokens Bearer, gérer l'accès aux locataires et projets, et implémenter des modèles d'intégration API sécurisés.

Vue d'ensemble de l'authentification

mindzieAPI utilise l'authentification par token Bearer combinée aux identifiants de locataire et de projet pour fournir un accès sécurisé multi-locataires aux ressources mindzie.

Types de clés API

mindzieAPI prend en charge deux types de clés API avec différents niveaux d'accès :

Clés API Locataire (Standard)

Les clés API Locataire sont limitées à un locataire spécifique et sont utilisées pour la plupart des opérations API :

Accéder aux projets, jeux de données, investigations et tableaux de bord au sein du locataire
Exécuter des notebooks et des blocs
Gérer les ressources au niveau du projet

Création dans : Paramètres -> Clés API (dans mindzieStudio)

Clés API Globales (Clés API Serveur)

Les clés API Globales disposent d’un accès administratif à l’échelle du système et sont requises pour :

API Locataire - Créer, lister, mettre à jour et supprimer des locataires
API Utilisateur (Globale) - Créer et gérer des utilisateurs sur tous les locataires
Assigner des utilisateurs aux locataires

Création dans : /admin/global-api-keys (Accès administrateur requis)

IMPORTANT : Les points d'extrémité API Locataire (/api/tenant) requièrent une clé API Globale. Les clés API spécifiques à un locataire ne peuvent pas accéder à ces points et recevront une réponse 401 Unauthorized.

En-têtes requis

Pour les opérations limitées au locataire

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

L'identifiant du locataire est généralement inclus dans le chemin URL (par exemple, /api/{tenantId}/project).

Pour les opérations globales (gestion locataire/utilisateur)

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Note de sécurité : Utilisez toujours HTTPS lors des requêtes API pour protéger vos tokens d’accès en transit.

Obtention des tokens d’accès

Serveur Enterprise

Pour les déploiements Enterprise Server, contactez votre administrateur mindzie pour obtenir :

Token d’accès API
Identifiant du locataire (format GUID)
Identifiant du projet (format GUID)
URL de base de l’API pour votre instance

Déploiement SaaS

Pour les utilisateurs SaaS, les tokens d’accès peuvent être générés via :

Interface utilisateur mindzie Studio (Paramètres → Clés API)
Contact avec votre administrateur de compte
Utilisation des points d’authentification (si activés)

Tester l’authentification

Utilisez les points de test ping pour vérifier votre configuration d’authentification :

Test de connectivité basique

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

Test authentifié

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"

Réponse réussie

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

Bonnes pratiques de sécurité

Sécurité des tokens

Stockez les tokens de manière sécurisée via des variables d’environnement ou des systèmes sécurisés de gestion des identifiants.

Expiration des tokens

Surveillez l’expiration des tokens et implémentez des mécanismes de rafraîchissement pour maintenir un accès ininterrompu.

Multi-locataire

Chaque token est limité à des locataires et projets spécifiques pour garantir l’isolation sécurisée des données.

Exemples d’implémentation

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")
);

Gestion des erreurs

Erreurs d’authentification courantes

Code statut	Erreur	Description	Solution
`401`	Unauthorized	Token d’accès invalide ou manquant	Vérifier le token et s'assurer qu'il n'est pas expiré
`403`	Forbidden	Token valide mais permissions insuffisantes	Vérifier l’accès locataire/projet ou demander les permissions
`400`	Bad Request	En-têtes requis manquants	S’assurer que X-Tenant-Id et X-Project-Id sont fournis

Exemple de réponse d’erreur

{
  "error": "invalid_token",
  "message": "Le token d’accès fourni est invalide ou expiré",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

Étapes suivantes

Une fois l’authentification fonctionnelle, essayez le Guide de démarrage rapide pour effectuer vos premiers appels API ou explorez la documentation sur les Formats de réponse.