Kimlik Doğrulama

mindzieAPI'ye Güvenli Erişim

mindzieAPI ile Bearer token kullanarak nasıl kimlik doğrulaması yapacağınızı, kiracı ve proje erişimini yönetmeyi ve güvenli API entegrasyon kalıplarını nasıl uygulayacağınızı öğrenin.

Kimlik Doğrulama Genel Bakış

mindzieAPI, 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 seviyelerine sahip iki tür API anahtarını destekler:

Kiracı API Anahtarları (Standart)

Kiracı API Anahtarları belirli bir kiracıya özgüdür ve çoğu API işlemi için kullanılır:

Kiracı içindeki projelere, veri setlerine, araştırmalara ve panellere erişim
Not defterleri ve bloklar çalıştırma
Proje düzeyindeki kaynakları yönetme

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

Genel API Anahtarları (Sunucu API Anahtarları)

Genel API Anahtarları sistem çapında yönetici erişimine sahiptir ve aşağılar için gereklidir:

Tenant API - Kiracı oluşturma, listeleme, güncelleme ve silme
User API (Genel) - Tüm kiracılardaki kullanıcıları oluşturma ve yönetme
Kullanıcıları kiracılara atama

Oluşturma yeri: /admin/global-api-keys (bir yönetici rolü gerektirir: Developer, IT Admin, Administrator veya Server Administrator)

ÖNEMLİ: Tenant API uç noktaları (/api/tenant) için Genel API Anahtarı gereklidir. Normal kiracı bazlı API anahtarları bu uç noktalara erişemez ve 401 Yetkisiz yanıtı alır.

Gerekli Başlıklar

Kiracı Kapsamlı İşlemler İçin

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

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

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

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

Güvenlik Notu: Erişim tokenlerinizin taşınırken korunması için API isteklerinde her zaman HTTPS kullanın.

Erişim Tokeni Alma

Enterprise Server

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

API erişim tokeni
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 tokenleri şu yollarla oluşturulabilir:

mindzie Studio kullanıcı arayüzü (Settings → API Keys)
Hesap yöneticinize başvurarak
Kimlik doğrulama uç noktalarını kullanarak (aktifse)

Kimlik Doğrulamayı Test Etme

Kimlik doğrulama kurulumunuzu doğrulamak için ping uç noktalarını kullanın:

Temel Bağlantı Testi

Bu uç nokta kimlik doğrulama gerektirmez ve sunucuya erişilebilirliğin doğrulanması için faydalıdır.

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

Kimlik Doğrulamalı Test

Bu uç nokta geçerli bir Bearer token gerektirir ve tokenınızın belirtilen kiracı ve projeye erişimi olduğunu doğrular.

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

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

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

Token Süresi

Tokenlerin süresinin dolmasını izleyin ve kesintisiz erişimi sağlamak için yenileme mekanizmaları uygulayın.

Çok Kiracılı

Her token belirli kiracılar ve projelerle sınırlandırılmıştır ve bu sayede 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("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}")

# 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 tokeni	Tokenu doğrulayın ve süresinin dolmadığından emin olun
`403`	Yasaklandı	Geçerli token ancak 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'in sağlandığından emin olun

Örnek Hata Yanıtı

{
  "error": "invalid_token",
  "message": "The provided access token is invalid or expired",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

Sonraki Adımlar

Kimlik doğrulama çalışır duruma geldiğinde, ilk API çağrılarınızı yapmak için Hızlı Başlangıç Rehberi veya Yanıt Formatları dokümantasyonunu keşfedin.