Authentification

Accès sécurisé à mindzieAPI

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

Vue d'ensemble de l'authentification

mindzieAPI utilise une authentification par jeton Bearer combinée à des 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, ensembles de données, enquêtes 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 (Global) - Créer et gérer les 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é Tenant API (/api/tenant) nécessitent une clé API Globale. Les clés API spécifiques au locataire ne peuvent pas accéder à ces endpoints 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 de l'URL (par exemple, /api/{tenantId}/project).

Pour les opérations globales (gestion des locataires/utilisateurs)

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 Entreprise

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

Jeton 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 jetons d'accès peuvent être générés via :

L'interface utilisateur mindzie Studio (Paramètres → Clés API)
Le contact avec votre administrateur de compte
L'utilisation des points d'extrémité d'authentification (si activés)

Tester l'authentification

Utilisez les endpoints ping pour vérifier la configuration de votre 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 jetons

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

Expiration des jetons

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

Multi-locataires

Chaque jeton 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}")

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

// Utilisation
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 courantes d’authentification

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 au locataire/projet ou demandez les permissions
`400`	Requête incorrecte	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 opérationnelle, essayez le Guide de démarrage rapide pour effectuer vos premières appels API ou explorez la documentation des Formats de réponse.