Autenticación
Acceso seguro a mindzieAPI
Aprenda cómo autenticarse con mindzieAPI utilizando tokens Bearer, manejar el acceso a inquilinos y proyectos, e implementar patrones seguros de integración API.
Visión general de la autenticación
mindzieAPI utiliza autenticación con token 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 admite 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
- Administrar recursos a nivel de proyecto
Creación en: Settings -> API Keys (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:
- Tenant API - Crear, listar, actualizar y eliminar inquilinos
- User API (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 Tenant API (/api/tenant) requieren una clave API global. Las claves API regulares específicas de inquilino no pueden acceder a estos endpoints y recibirán una respuesta 401 Unauthorized.
Encabezados requeridos
Para operaciones limitadas a inquilinos
Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json
El ID del inquilino usualmente se incluye en la ruta 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 durante la transmisión.
Obtención de tokens de acceso
Servidor Empresarial
Para despliegues en Servidor Empresarial, contacte a su 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 pueden generarse a través de:
- Interfaz de usuario de mindzie Studio (Settings → API Keys)
- Contactando a su administrador de cuenta
- Usando los endpoints de autenticación (si están habilitados)
Prueba 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"]
}
Mejores prácticas de seguridad
Seguridad de tokens
Almacene los tokens de forma segura utilizando variables de entorno o sistemas seguros de gestión de credenciales.
Expiración de tokens
Monitoree la expiración de tokens y implemente mecanismos de renovación para mantener acceso ininterrumpido.
Multi-inquilino
Cada token está limitado a inquilinos y proyectos específicos para 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 |
Unauthorized | Token de acceso inválido o faltante | Verifique el token y asegúrese de que no haya expirado |
403 |
Forbidden | Token válido pero permisos insuficientes | Revise el acceso a inquilino/proyecto o solicite permisos |
400 |
Bad Request | Encabezados requeridos faltantes | Asegúrese de proporcionar X-Tenant-Id y X-Project-Id |
Ejemplo de respuesta de error
{
"error": "invalid_token",
"message": "The provided access token is invalid or expired",
"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 API o explore la documentación de Formatos de Respuesta.