Autenticación

Acceso Seguro a mindzieAPI

Aprenda cómo autenticarse con mindzieAPI usando tokens Bearer, gestionar el acceso a inquilinos y proyectos, e implementar patrones seguros de integración con la API.

Resumen de Autenticación

mindzieAPI utiliza autenticación con tokens Bearer combinada con identificadores de inquilino y proyecto para proporcionar acceso seguro y multi-inquilino a los recursos de mindzie.

Tipos de Claves API

mindzieAPI soporta dos tipos de claves API con diferentes niveles de acceso:

Claves API de Inquilino (Estándar)

Las Claves API de Inquilino están limitadas a un inquilino específico y se usan para la mayoría de las operaciones de la API:

Acceso a proyectos, conjuntos de datos, investigaciones y tableros dentro del inquilino
Ejecución de notebooks y bloques
Gestión de recursos a nivel de proyecto

Creación en: Configuración -> Claves API (dentro de mindzieStudio)

Claves API Globales (Claves API de Servidor)

Las Claves API Globales tienen acceso administrativo a nivel de sistema y son necesarias para:

API de Inquilino - Crear, listar, actualizar y eliminar inquilinos
API de Usuario (Global) - Crear y gestionar usuarios en todos los inquilinos
Asignar usuarios a inquilinos

Creación en: /admin/global-api-keys (Se requiere acceso de administrador)

IMPORTANTE: Los endpoints de la API de Inquilino (/api/tenant) requieren una Clave API Global. Las claves API específicas del inquilino no pueden acceder a estos endpoints y recibirán una respuesta 401 Unauthorized.

Encabezados Requeridos

Para Operaciones con Ámbito de Inquilino

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

El ID del inquilino generalmente se incluye en la ruta de la URL (por ejemplo, /api/{tenantId}/project).

Para Operaciones Globales (Gestión de Inquilinos/Usuarios)

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Nota de Seguridad: Siempre use HTTPS al realizar solicitudes a la API para proteger sus tokens de acceso durante la transmisión.

Obtención de Tokens de Acceso

Servidor Empresarial

Para despliegues en Servidor Empresarial, contacte a su administrador mindzie para obtener:

Token de acceso a la API
ID de inquilino (formato GUID)
ID de proyecto (formato GUID)
URL base de la API para su instancia

Despliegue SaaS

Para usuarios SaaS, los tokens se pueden generar a través de:

Interfaz de usuario de mindzie Studio (Configuración → Claves API)
Contactando a su administrador de cuentas
Usando los endpoints de autenticación (si están habilitados)

Pruebas de Autenticación

Utilice los endpoints de ping para verificar su configuración de autenticación:

Prueba Básica de Conectividad

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

Prueba Autenticada

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"

Respuesta Exitosa

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

Buenas Prácticas de Seguridad

Seguridad del Token

Almacene los tokens de forma segura utilizando variables de entorno o sistemas seguros de gestión de credenciales.

Expiración del Token

Monitoree la expiración de los tokens e implemente mecanismos de renovación para mantener el acceso ininterrumpido.

Multi-Inquilino

Cada token está limitado a inquilinos y proyectos específicos para garantizar el aislamiento seguro de los datos.

Ejemplos de Implementación

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

Manejo de Errores

Errores Comunes de Autenticación

Código de Estado	Error	Descripción	Solución
`401`	Unauthorized	Token de acceso inválido o ausente	Verifique el token y asegúrese que no esté expirado
`403`	Forbidden	Token válido pero permisos insuficientes	Verifique acceso a inquilino/proyecto o solicite permisos
`400`	Bad Request	Faltan encabezados requeridos	Asegúrese de que X-Tenant-Id y X-Project-Id estén presentes

Ejemplo de Respuesta de Error

{
  "error": "invalid_token",
  "message": "El token de acceso proporcionado es inválido o ha expirado",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

Próximos Pasos

Una vez que la autenticación funcione, pruebe la Guía de Inicio Rápido para realizar sus primeras llamadas a la API o explore la documentación de Formatos de Respuesta.