Authentification

Accès sécurisé à mindzieAPI

Apprenez à vous authentifier avec mindzieAPI en utilisant des jetons Bearer, à gérer l'accès aux locataires et projets, et à mettre en œuvre des modèles d'intégration API sécurisés.

Vue d'ensemble de l'authentification

mindzieAPI utilise l'authentification par jeton Bearer combinée aux identifiants de locataire et de projet pour fournir un accès sécurisé et multi-locataire 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 dans le locataire
Exécuter des notebooks et 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 ont un accès administratif à l’échelle du système et sont nécessaires pour :

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

Création dans : /admin/global-api-keys (requiert un rôle administratif : Développeur, Admin IT, Administrateur ou Administrateur Serveur)

IMPORTANT : Les points d’accès Tenant API (/api/tenant) nécessitent une clé API globale. Les clés API spécifiques au locataire ne peuvent pas accéder à ces points d’accès et recevront une réponse 401 Non autorisé.

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 (ex. : /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 jetons d'accès en transit.

Obtention des jetons d'accès

Serveur Enterprise

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

Jeton d'accès API
ID locataire (format GUID)
ID projet (format GUID)
URL de base API pour votre instance

Déploiement SaaS

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

L'interface utilisateur de mindzie Studio (Paramètres → Clés API)
Le contact de votre administrateur de compte
Les points d’authentification (si activés)

Test de l'authentification

Utilisez les points de terminaison ping pour vérifier votre configuration d'authentification :

Test de connectivité basique

Ce point d'accès ne nécessite pas d'authentification et est utile pour vérifier que le serveur est accessible.

curl -X GET "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/Action/unauthorized-ping"

Test authentifié

Ce point d’accès requiert un jeton Bearer valide et confirme que votre jeton a accès au locataire et au projet spécifiés.

curl -X GET "https://your-mindzie-instance.com/api/{tenantId}/{projectId}/Action/ping" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

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 jetons

Stockez les jetons en toute sécurité en utilisant des variables d'environnement ou des systèmes de gestion sécurisée des identifiants.

Expiration des jetons

Surveillez l'expiration des jetons et implémentez des mécanismes de rafraîchissement pour garantir un accès ininterrompu.

Multi-locataire

Chaque jeton est limité à des locataires et projets spécifiques pour assurer 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`	Non autorisé	Jeton d'accès invalide ou manquant	Vérifiez le jeton et assurez-vous qu'il n'est pas expiré
`403`	Interdit	Jeton valide mais permissions insuffisantes	Vérifiez l'accès locataire/projet ou demandez les permissions
`400`	Mauvaise requête	En-têtes requis manquants	Assurez-vous que X-Tenant-Id et X-Project-Id sont fournis

Exemple de réponse d'erreur

{
  "error": "invalid_token",
  "message": "Le jeton 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 des Formats de réponse.