Kimlik Doğrulama

mindzieAPI'ye Güvenli Erişim

mindzieAPI ile Bearer token kullanarak nasıl kimlik doğrulama yapılacağını, kiracı ve proje erişimini nasıl yöneteceğinizi ve güvenli API entegrasyonu desenlerini nasıl uygulayacağınızı öğrenin.

Kimlik Doğrulama Genel Bakış

mindzieAPI, mindzie kaynaklarına güvenli, çok kiracılı erişim sağlamak için Bearer token kimlik doğrulamasını kiracı ve proje tanımlayıcıları ile birleştirir.

API Anahtarı Türleri

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

Kiracı API Anahtarları (Standart)

Kiracı API Anahtarları belirli bir kiracıya yönelik olup çoğu API işleminde kullanılır:

Kiracı içindeki projelere, veri kümelerine, incelemelere ve panellere erişim
Notebook ve blokları çalıştırma
Proje seviyesinde kaynakları yönetme

Oluşturma yeri: Settings -> API Keys (mindzieStudio içinde)

Global API Anahtarları (Sunucu API Anahtarları)

Global API Anahtarları sistem genelinde yönetici erişimine sahiptir ve aşağıdaki işlemler için gereklidir:

Kiracı API - Kiracı oluşturma, listeleme, güncelleme ve silme
Kullanıcı API (Global) - Tüm kiracılar için kullanıcı oluşturma ve yönetme
Kullanıcıları kiracılara atama

Oluşturma yeri: /admin/global-api-keys (Yönetici erişimi gereklidir)

ÖNEMLİ: Kiracı API uç noktaları (/api/tenant) Global API Anahtarı gerektirir. Normal kiracıya özgü API anahtarları bu uç noktalara erişemez ve 401 Yetkisiz yanıtı alır.

Gerekli Başlıklar

Kiracı Odaklı İşlemler İçin

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

Kiracı kimliği genellikle URL yolunda yer alır (örneğin, /api/{tenantId}/project).

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

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Güvenlik Notu: API isteklerinde erişim tokenlarınızın transfer sırasında korunması için her zaman HTTPS kullanın.

Erişim Tokenleri Alma

Enterprise Sunucu

Enterprise Server dağıtımları için, aşağıdakileri almak üzere mindzie yöneticinizle iletişime geçin:

API erişim tokenı
Kiracı ID'si (GUID formatında)
Proje ID'si (GUID formatında)
Örneğiniz için 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ü (Settings → API Keys)
Hesap yöneticinizle iletişime geçerek
Kimlik doğrulama uç noktalarını kullanarak (etkinleştirilmişse)

Kimlik Doğrulamayı Test Etme

Kimlik doğrulama kurulumunuzu 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 şekilde saklayın.

Token Süresi Dolumu

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

Çok Kiracılılık

Her token belirli kiracılar ve projeler için kapsamlandırılmıştır, böylece 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 oldu: {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`	Yasaklı	Geçerli token fakat yetersiz izinler	Kiracı/proje erişimini kontrol edin veya izin talep edin
`400`	Hatalı İstek	Gerekli başlıklar eksik	X-Tenant-Id ve X-Project-Id sağlandığından emin olun

Örnek Hata Yanıtı

{
  "error": "invalid_token",
  "message": "Sağlanan 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ıştıktan sonra, ilk API çağrılarınızı yapmak için Hızlı Başlangıç Kılavuzu veya Yanıt Formatları dökümantasyonunu inceleyin.