Autenticación

Acceso seguro a mindzieAPI

Aprenda cómo autenticarse con mindzieAPI usando tokens Bearer, administrar el acceso a inquilinos y proyectos, e implementar patrones de integración segura de 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 API:

Acceder a proyectos, conjuntos de datos, investigaciones y paneles dentro del inquilino
Ejecutar notebooks y bloques
Gestionar recursos a nivel de proyecto

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

Claves API Globales (Claves API de Servidor)

Las claves API Globales tienen acceso administrativo a nivel del sistema y son necesarias para:

API de Inquilinos - Crear, listar, actualizar y eliminar inquilinos
API de Usuarios (Global) - Crear y administrar usuarios a través de todos los inquilinos
Asignar usuarios a inquilinos

Crear en: /admin/global-api-keys (requiere un rol administrativo: Desarrollador, Admin de TI, Administrador o Administrador de Servidor)

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

Encabezados Requeridos

Para Operaciones con Ámbito de Inquilino

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

El ID del inquilino se incluye típicamente 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 hacer solicitudes API para proteger sus tokens de acceso en tránsito.

Obtención de Tokens de Acceso

Servidor Empresarial

Para despliegues en Servidor Empresarial, contacte al administrador de mindzie para obtener:

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

Despliegue SaaS

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

La interfaz de usuario de mindzie Studio (Configuración → Claves API)
Contactando a su administrador de cuenta
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

Este endpoint no requiere autenticación y es útil para verificar que el servidor esté accesible.

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

Prueba autenticada

Este endpoint requiere un token Bearer válido y confirma que su token tiene acceso al inquilino y proyecto especificados.

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

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

Mejores Prácticas de Seguridad

Seguridad del Token

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

Expiración del Token

Monitoree la expiración del token e implemente mecanismos de renovación para mantener acceso ininterrumpido.

Multi-inquilino

Cada token está limitado a inquilinos y proyectos específicos para garantizar aislamiento seguro de 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}")

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

// Uso
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`	No autorizado	Token de acceso inválido o faltante	Verifique el token y asegúrese que no esté expirado
`403`	Prohibido	Token válido pero permisos insuficientes	Revise acceso a inquilino/proyecto o solicite permisos
`400`	Solicitud incorrecta	Encabezados requeridos faltantes	Asegúrese que X-Tenant-Id y X-Project-Id estén provistos

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 hacer sus primeras llamadas a la API o explore la documentación de Formatos de Respuesta.