Kimlik Doğrulama

mindzieAPI'ye Güvenli Erişim

Bearer token kullanarak mindzieAPI ile nasıl kimlik doğrulaması yapılacağını, tenant ve proje erişiminin nasıl yönetileceğini ve güvenli API entegrasyon desenlerinin nasıl uygulanacağını öğrenin.

Kimlik Doğrulama Genel Bakış

mindzieAPI, Bearer token kimlik doğrulamasını tenant ve proje kimlik belirleyicileri ile birleştirerek mindzie kaynaklarına güvenli, çok-tenant erişim sağlar.

API Anahtarı Türleri

mindzieAPI, farklı erişim seviyeleriyle iki tür API anahtarı destekler:

Tenant API Anahtarları (Standart)

Tenant API Anahtarları belirli bir tenant ile sınırlıdır ve çoğu API işlemi için kullanılır:

Tenant içindeki projelere, veri setlerine, araştırmalara ve gösterge tablolarına erişim
Notebook ve blokları çalıştırma
Proje düzeyinde kaynakları yönetme

Oluşturulduğu yer: Ayarlar -> API Anahtarları (mindzieStudio içinde)

Global API Anahtarları (Sunucu API Anahtarları)

Global API Anahtarları sistem genelinde yönetici erişimine sahiptir ve gereklidir:

Tenant API - Tenant oluşturma, listeleme, güncelleme ve silme
Kullanıcı API (Global) - Tüm tenantlarda kullanıcı oluşturma ve yönetme
Kullanıcıları tenantlara atama

Oluşturulduğu yer: /admin/global-api-keys (Yönetici erişimi gerekir)

ÖNEMLİ: Tenant API uç noktaları (/api/tenant), Global API Anahtarı gerektirir. Normal tenant'a özgü API anahtarları bu uç noktalara erişemez ve 401 Yetkisiz yanıtı alırlar.

Gerekli Başlıklar

Tenant-Sınırlı İşlemler İçin

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

Tenant ID genellikle URL yolu içinde verilir (örneğin, /api/{tenantId}/project).

Global İşlemler İçin (Tenant/Kullanıcı Yönetimi)

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Güvenlik Notu: API istekleri yaparken her zaman HTTPS kullanın, böylece erişim tokenlarınız aktarım sırasında korunur.

Erişim Tokenları Alma

Kurumsal Sunucu

Kurumsal Sunucu dağıtımları için, aşağıları almak üzere mindzie yöneticinizle iletişime geçin:

API erişim tokenı
Tenant ID (GUID formatında)
Proje ID (GUID formatında)
Örneğinize ait temel API URL'si

SaaS Dağıtımı

SaaS kullanıcıları için erişim tokenları şu yollarla oluşturulabilir:

mindzie Studio kullanıcı arayüzü (Ayarlar → API Anahtarları)
Hesap yöneticinizle iletişim
Kimlik doğrulama uç noktalarını kullanarak (aktifse)

Kimlik Doğrulamanın Test Edilmesi

Kimlik doğrulama yapılandırmanızı doğrulamak için ping uç noktalarını kullanın:

Temel Bağlantı Testi

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

Kimlik Doğrulamalı Test

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"

Başarılı Yanıt

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

Güvenlik En İyi Uygulamaları

Token Güvenliği

Tokenları ortam değişkenleri veya güvenli kimlik bilgisi yönetim sistemleri kullanarak güvenli bir şekilde saklayın.

Token Süre Sonu

Token sona erme sürelerini izleyin ve kesintisiz erişim için yenileme mekanizmaları uygulayın.

Çok-Tenant

Her token belirli tenantlar ve projeler ile sınırlıdır, böylece güvenli veri izolasyonu sağlanır.

Uygulama Örnekleri

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("Gerekli ortam değişkenleri eksik")

    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 isteği başarısız: {e}")

# Kullanım
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);
    }
}

// Kullanım
var client = new MindzieApiClient(
    Environment.GetEnvironmentVariable("MINDZIE_API_URL"),
    Environment.GetEnvironmentVariable("MINDZIE_ACCESS_TOKEN"),
    Environment.GetEnvironmentVariable("MINDZIE_TENANT_ID"),
    Environment.GetEnvironmentVariable("MINDZIE_PROJECT_ID")
);

Hata Yönetimi

Yaygın Kimlik Doğrulama Hataları

Durum Kodu	Hata	Açıklama	Çözüm
`401`	Yetkisiz	Geçersiz veya eksik erişim tokenı	Tokenı doğrulayın ve süresinin dolmadığından emin olun
`403`	Yasaklandı	Geçerli token ancak yetersiz izinler	Tenant/proje erişimini kontrol edin veya izin isteyin
`400`	Geçersiz İstek	Gerekli başlıklar eksik	X-Tenant-Id ve X-Project-Id'nin sağlandığından emin olun

Örnek Hata Yanıtı

{
  "error": "invalid_token",
  "message": "Verilen erişim tokenı geçersiz veya süresi dolmuş",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

Sonraki Adımlar

Kimlik doğrulama çalışır hale geldikten sonra, ilk API çağrılarınızı yapmak için Hızlı Başlangıç Kılavuzu veya Yanıt Formatları belgelerini keşfedin.