認証
mindzieAPIへの安全なアクセス
Bearerトークンを使用したmindzieAPIの認証方法、テナントおよびプロジェクトアクセスの管理、安全なAPI統合パターンの実装方法を学びましょう。
認証の概要
mindzieAPIはBearerトークン認証とテナントおよびプロジェクト識別子を組み合わせて、多テナント環境でのmindzieリソースへの安全なアクセスを提供します。
APIキーの種類
mindzieAPIは異なるアクセスレベルを持つ2種類のAPIキーをサポートしています。
テナントAPIキー（標準）
テナントAPIキーは特定のテナントにスコープされ、ほとんどのAPI操作に使用されます：
- テナント内のプロジェクト、データセット、調査、ダッシュボードへのアクセス
- ノートブックやブロックの実行
- プロジェクトレベルのリソース管理
作成場所: Settings -> API Keys (mindzieStudio内)
グローバルAPIキー（サーバーAPIキー）
グローバルAPIキーはシステム全体の管理アクセス権を持ち、以下に必要です：
- Tenant API - テナントの作成、一覧取得、更新、削除
- User API (Global) - 全てのテナントにわたるユーザーの作成と管理
- ユーザーをテナントに割り当てる
作成場所: /admin/global-api-keys (管理者アクセスが必要)
重要: Tenant 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}")
# Usage
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);
}
}
// Usage
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": "The provided access token is invalid or expired",
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "req_12345"
}
次のステップ
認証が正常に動作したら、クイックスタートガイドを試して最初のAPIコールを行うか、レスポンスフォーマットのドキュメントを参照してください。