グローバルユーザー操作

グローバルユーザーエンドポイントはシステム全体のユーザー管理機能を提供します。これらのエンドポイントはグローバルAPIキーが必要であり、すべてのテナントのユーザーにアクセスできます。

認証

このページのすべてのエンドポイントはグローバルAPIキーを必要とします。テナントスコープのAPIキーを使用すると、401 Unauthorizedエラーが返されます。

---

すべてのユーザー一覧取得

GET /api/user

すべてのテナントのユーザーをページネーション付きで取得します。

クエリパラメーター

パラメーター	種別	デフォルト	説明
page	integer	1	ページ番号
pageSize	integer	50	1ページあたりのアイテム数（最大: 1000）
includeDisabled	boolean	false	無効化ユーザーを含むか
role	string	null	ロール名による絞り込み
search	string	null	メールアドレスまたは表示名による検索

レスポンス (200 OK)

{
  "users": [
    {
      "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "john.smith@example.com",
      "displayName": "John Smith",
      "firstName": "John",
      "lastName": "Smith",
      "roleName": "Analyst",
      "disabled": false,
      "isServiceAccount": false,
      "homeTenantId": null,
      "homeTenantName": null,
      "lastLogin": "2024-01-15T10:30:00Z",
      "tenantCount": 2,
      "tenantNames": "acme-corp, globex-inc",
      "dateCreated": "2024-01-01T00:00:00Z"
    }
  ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 50
}

ユーザーオブジェクトのフィールド

フィールド	種別	説明
userId	GUID	ユーザーの一意識別子
email	string	ユーザーのメールアドレス（一意）
displayName	string	ユーザーの表示名
firstName	string	ユーザーの名
lastName	string	ユーザーの姓
roleName	string	ユーザーのロール（Administrator、TenantAdmin、Analystなど）
disabled	boolean	ユーザーアカウントが無効かどうか
isServiceAccount	boolean	サービスアカウントかどうか
homeTenantId	GUID	サービスアカウントのホームテナントID
homeTenantName	string	サービスアカウントのホームテナント名
lastLogin	datetime	最終ログイン日時
tenantCount	integer	ユーザーが割り当てられたテナント数
tenantNames	string	カンマ区切りのテナント名リスト
dateCreated	datetime	アカウント作成日時

エラー応答

Unauthorized (401):

{
  "error": "This endpoint requires a Global API key. Tenant-specific API keys cannot list all users.",
  "hint": "Use /api/tenant/{tenantId}/user to list users for a specific tenant, or create a Global API key at /admin/global-api-keys"
}

---

ユーザー作成

POST /api/user

システムに新しいユーザーを作成します。ユーザーはどのテナントにも割り当てられません。

リクエストボディ

{
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "roleName": "Analyst"
}

リクエストフィールド

フィールド	種別	必須	説明
email	string	はい	ユーザーのメールアドレス（一意である必要があります）
displayName	string	はい	表示名（2～100文字）
firstName	string	いいえ	名（最大50文字）
lastName	string	いいえ	姓（最大50文字）
roleName	string	はい	ロール名（Roles & Permissions参照）

レスポンス (201 Created)

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "message": "User created successfully"
}

エラー応答

Conflict (409):

{
  "error": "A user with email 'john.smith@example.com' already exists"
}

---

ユーザーIDによる取得

GET /api/user/{userId}

特定ユーザーの詳細情報を取得します。

パスパラメーター

パラメーター	種別	説明
userId	GUID	ユーザー識別子

レスポンス (200 OK)

テナント割り当てを含む完全なユーザーオブジェクトを返します。

エラー応答

Not Found (404):

{
  "error": "User not found with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

---

ユーザー更新

PUT /api/user/{userId}

ユーザーのプロパティを更新します。指定されたフィールドのみが更新されます。

パスパラメーター

パラメーター	種別	説明
userId	GUID	ユーザー識別子

リクエストボディ

{
  "displayName": "Jane Smith",
  "roleName": "TenantAdmin",
  "disabled": false,
  "isServiceAccount": true,
  "homeTenantId": "12345678-1234-1234-1234-123456789012"
}

リクエストフィールド

フィールド	種別	必須	説明
displayName	string	いいえ	新しい表示名
roleName	string	いいえ	新しいロール名
disabled	boolean	いいえ	アカウントの有効/無効
isServiceAccount	boolean	いいえ	サービスアカウントフラグ
homeTenantId	GUID	条件付き	サービスアカウントにする場合に必須

サービスアカウントルール

• サービスアカウントにできるのはAdministratorとTenantAdminロールのみ
• サービスアカウントに昇格する場合はhomeTenantIdが必須
• サービスアカウントから降格する場合はhomeTenantIdが自動クリアされる

レスポンス (200 OK)

{
  "message": "User updated successfully"
}

---

メールアドレスによるユーザー取得

GET /api/user/by-email/{email}

メールアドレスでユーザーを取得します。

パスパラメーター

パラメーター	種別	説明
email	string	ユーザーのメールアドレス（URLエンコード済み）

レスポンス (200 OK)

完全なユーザーオブジェクトを返します。

---

ユーザーのテナント一覧取得

GET /api/user/{userId}/tenants

ユーザーに割り当てられたすべてのテナントを取得します。

パスパラメーター

パラメーター	種別	説明
userId	GUID	ユーザー識別子

レスポンス (200 OK)

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.smith@example.com",
  "displayName": "John Smith",
  "tenants": [
    {
      "tenantId": "12345678-1234-1234-1234-123456789012",
      "tenantName": "acme-corp",
      "displayName": "Acme Corporation",
      "dateAssigned": "2024-01-15T10:30:00Z"
    }
  ]
}

---

実装例

cURL

# すべてのユーザー一覧取得（グローバルAPIキー必須）
curl -X GET "https://your-mindzie-instance.com/api/user?page=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# 名前でユーザー検索
curl -X GET "https://your-mindzie-instance.com/api/user?search=john" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# ロールでフィルタリング
curl -X GET "https://your-mindzie-instance.com/api/user?role=Analyst" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# 新規ユーザー作成
curl -X POST "https://your-mindzie-instance.com/api/user" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.smith@example.com",
    "displayName": "John Smith",
    "roleName": "Analyst"
  }'

# ユーザーIDで取得
curl -X GET "https://your-mindzie-instance.com/api/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# メールアドレスで取得
curl -X GET "https://your-mindzie-instance.com/api/user/by-email/john.smith%40example.com" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

# ユーザーのテナント取得
curl -X GET "https://your-mindzie-instance.com/api/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890/tenants" \
  -H "Authorization: Bearer YOUR_GLOBAL_API_KEY"

Python

import requests

BASE_URL = 'https://your-mindzie-instance.com'

class GlobalUserManager:
    def __init__(self, global_api_key):
        """GLOBAL APIキー（テナント固有ではない）で初期化します。"""
        self.headers = {
            'Authorization': f'Bearer {global_api_key}',
            'Content-Type': 'application/json'
        }

    def list_users(self, page=1, page_size=50, include_disabled=False,
                   role=None, search=None):
        """すべてのテナントのユーザーを一覧取得します。"""
        url = f'{BASE_URL}/api/user'
        params = {
            'page': page,
            'pageSize': page_size,
            'includeDisabled': include_disabled
        }
        if role:
            params['role'] = role
        if search:
            params['search'] = search

        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def create_user(self, email, display_name, role_name,
                    first_name=None, last_name=None):
        """新しいユーザーを作成します（テナント割り当てなし）。"""
        url = f'{BASE_URL}/api/user'
        payload = {
            'email': email,
            'displayName': display_name,
            'roleName': role_name
        }
        if first_name:
            payload['firstName'] = first_name
        if last_name:
            payload['lastName'] = last_name

        response = requests.post(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_user(self, user_id):
        """ユーザーIDで取得します。"""
        url = f'{BASE_URL}/api/user/{user_id}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_user_by_email(self, email):
        """メールアドレスでユーザーを取得します。"""
        from urllib.parse import quote
        url = f'{BASE_URL}/api/user/by-email/{quote(email, safe="")}'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def update_user(self, user_id, display_name=None, role_name=None,
                    disabled=None, is_service_account=None, home_tenant_id=None):
        """ユーザー属性を更新します。"""
        url = f'{BASE_URL}/api/user/{user_id}'
        payload = {}
        if display_name is not None:
            payload['displayName'] = display_name
        if role_name is not None:
            payload['roleName'] = role_name
        if disabled is not None:
            payload['disabled'] = disabled
        if is_service_account is not None:
            payload['isServiceAccount'] = is_service_account
        if home_tenant_id is not None:
            payload['homeTenantId'] = home_tenant_id

        response = requests.put(url, json=payload, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def get_user_tenants(self, user_id):
        """ユーザーに割り当てられたすべてのテナントを取得します。"""
        url = f'{BASE_URL}/api/user/{user_id}/tenants'
        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

# 使用例
manager = GlobalUserManager('your-global-api-key')

# すべてのアナリストを一覧
analysts = manager.list_users(role='Analyst')
print(f"アナリスト合計: {analysts['totalCount']}")

# 新しいユーザー作成
new_user = manager.create_user(
    email='new.analyst@example.com',
    display_name='New Analyst',
    role_name='Analyst',
    first_name='New',
    last_name='Analyst'
)
print(f"作成したユーザーID: {new_user['userId']}")

# ユーザーのテナント割り当て取得
user_id = new_user['userId']
tenants = manager.get_user_tenants(user_id)
print(f"ユーザーは{len(tenants['tenants'])}テナントに割り当てられています")

JavaScript/Node.js

const BASE_URL = 'https://your-mindzie-instance.com';

class GlobalUserManager {
  constructor(globalApiKey) {
    this.headers = {
      'Authorization': `Bearer ${globalApiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async listUsers(options = {}) {
    const params = new URLSearchParams({
      page: options.page || 1,
      pageSize: options.pageSize || 50,
      includeDisabled: options.includeDisabled || false
    });
    if (options.role) params.append('role', options.role);
    if (options.search) params.append('search', options.search);

    const url = `${BASE_URL}/api/user?${params}`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async createUser(email, displayName, roleName) {
    const url = `${BASE_URL}/api/user`;
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ email, displayName, roleName })
    });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async getUser(userId) {
    const url = `${BASE_URL}/api/user/${userId}`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }

  async getUserTenants(userId) {
    const url = `${BASE_URL}/api/user/${userId}/tenants`;
    const response = await fetch(url, { headers: this.headers });
    if (!response.ok) throw new Error(`Failed: ${response.status}`);
    return await response.json();
  }
}

// 使用例
const manager = new GlobalUserManager('your-global-api-key');

// すべてのユーザー一覧取得
const users = await manager.listUsers();
console.log(`ユーザー合計: ${users.totalCount}`);

// ユーザー作成してテナント割り当てを確認
const newUser = await manager.createUser(
  'new@example.com',
  'New User',
  'Analyst'
);
const tenants = await manager.getUserTenants(newUser.userId);
console.log(`割り当てられたテナント数: ${tenants.tenants.length}`);