認証

mindzieAPIへの安全なアクセス

Bearerトークンを使ったmindzieAPIの認証方法、テナントおよびプロジェクトアクセスの管理、安全なAPI統合パターンの実装方法を学びましょう。

認証の概要

mindzieAPIは、Bearerトークン認証とテナント・プロジェクト識別子を組み合わせて、mindzieリソースへのセキュアなマルチテナントアクセスを提供します。

APIキーの種類

mindzieAPIでは、異なるアクセスレベルを持つ2種類のAPIキーをサポートしています。

テナントAPIキー（標準）

テナントAPIキーは特定のテナントにスコープされ、多くのAPI操作に使用されます：

テナント内のプロジェクト、データセット、調査、ダッシュボードへのアクセス
ノートブックやブロックの実行
プロジェクトレベルのリソース管理

作成場所： Settings -> API Keys（mindzieStudio内）

グローバルAPIキー（サーバーAPIキー）

グローバルAPIキーはシステム全体の管理アクセス権を持ち、以下に必要です：

テナントAPI - テナントの作成、一覧表示、更新、削除
ユーザーAPI（グローバル） - すべてのテナントのユーザーの作成・管理
ユーザーのテナントへの割り当て

作成場所： /admin/global-api-keys（管理者アクセス必要）

重要： テナントAPIエンドポイント（/api/tenant）はグローバルAPIキーが必要です。通常のテナント固有APIキーではこれらのエンドポイントにアクセスできず、401 Unauthorizedエラーが返されます。

必須ヘッダー

テナントスコープ操作の場合

Authorization: Bearer YOUR_TENANT_API_KEY
Content-Type: application/json

テナントIDは通常URLパスに含まれます（例：/api/{tenantId}/project）。

グローバル操作（テナント・ユーザー管理）の場合

Authorization: Bearer YOUR_GLOBAL_API_KEY
Content-Type: application/json

セキュリティ注意： APIリクエストは常にHTTPSを使用して、アクセス・トークンの送信中の保護を確実にしてください。

アクセストークンの取得

エンタープライズサーバーの場合

エンタープライズサーバー環境では、mindzie管理者に連絡して以下の情報を取得してください：

APIアクセス・トークン
テナントID（GUID形式）
プロジェクトID（GUID形式）
インスタンスのベースAPI URL

SaaS展開の場合

SaaS利用者は以下の方法でトークンを生成できます：

mindzie Studioのユーザーインターフェース（Settings → API Keys）
アカウント管理者への連絡
認証エンドポイントの利用（有効な場合）

認証のテスト

pingエンドポイントを使用し認証設定を検証します：

基本接続テスト

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

認証済みテスト

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"

成功レスポンス例

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

セキュリティのベストプラクティス

トークンのセキュリティ

トークンは環境変数や安全な資格情報管理システムを使って安全に保存してください。

トークンの有効期限

トークンの有効期限を監視し、アクセス中断を防ぐために更新機構を実装してください。

マルチテナント

各トークンは特定のテナントとプロジェクトにスコープされており、安全なデータ分離を保証します。

実装例

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

# 使用例
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);
    }
}

// 使用例
var client = new MindzieApiClient(
    Environment.GetEnvironmentVariable("MINDZIE_API_URL"),
    Environment.GetEnvironmentVariable("MINDZIE_ACCESS_TOKEN"),
    Environment.GetEnvironmentVariable("MINDZIE_TENANT_ID"),
    Environment.GetEnvironmentVariable("MINDZIE_PROJECT_ID")
);

エラーハンドリング

一般的な認証エラー

ステータスコード	エラー	説明	解決策
`401`	Unauthorized	アクセス・トークンが無効または欠如	トークンを確認し、有効期限切れでないことを確認
`403`	Forbidden	有効なトークンだが権限不足	テナント/プロジェクトのアクセス権を確認または権限をリクエスト
`400`	Bad Request	必須ヘッダーが欠けている	X-Tenant-Id と X-Project-Id が提供されていることを確認

エラー応答例

{
  "error": "invalid_token",
  "message": "提供されたアクセス・トークンが無効または期限切れです",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_12345"
}

次のステップ

認証が動作したら、最初のAPI呼び出しを行うためにクイックスタートガイドを試すか、レスポンス形式のドキュメントを参照してください。