> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Management API

> Connect AI の Management API は、エンタープライズプラットフォームの管理をプログラム的に制御する手段を提供します。手動の UI 操作なしで、ユーザー、サービスアカウント、ロールを管理するために使用します。

Management API のベース URL は `https://cloud.cdata.com/api/v1/admin` です。

<Note>
  Management API は、現在デザインパートナープログラムの一環としてベータ提供されています。
</Note>

## 認証

Management API のすべてのリクエストでは、Client Id と Client Secret を使用する OAuth 2.0 クライアント認証情報を使用する必要があります。既存の PAT や Basic 認証の認証情報はこの API では動作しません。

**手順 1: Bearer トークンをリクエストする**

```bash theme={null}
curl -X POST https://cloud-login.cdata.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<ClientId>&client_secret=<ClientSecret>"
```

**手順 2: Management API を呼び出す**

```bash theme={null}
curl https://cloud.cdata.com/api/v1/admin/users \
  -H "Authorization: Bearer <access_token>"
```

## ページネーション

コレクションレスポンスはカーソルベースのページネーションを使用します。すべてのコレクションレスポンスは同じエンベロープを共有します：

```json theme={null}
{
  "items": [ ... ],
  "limit": 20,
  "next_cursor": "eyJpZCI6IjEyMyJ9"
}
```

| フィールド          | 説明                                                                   |
| :------------- | :------------------------------------------------------------------- |
| *items*        | 結果オブジェクトの配列。                                                         |
| *limit*        | リクエストされたページごとのアイテム最大数。                                               |
| *next\_cursor* | 次のページを取得するには、この値を `cursor` クエリパラメータとして渡します。次のページが存在しない場合は `null` です。 |

合計件数は返されません。`next_cursor` が `null` になるまで反復してください。

## エラー

エラーレスポンスは一貫した構造を使用します：

```json theme={null}
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "The specified user does not exist."
  }
}
```

`code` フィールドは、プログラム処理に適した `SCREAMING_SNAKE_CASE` 文字列です。`message` フィールドは人間が読める説明です。

## ID

Management API は 2 種類の ID を管理します。

### ユーザー

組織で SCIM が構成されている場合、人間のユーザーは SCIM によってプロビジョニングされ、ライフサイクル管理されます。Management API は、直接オーバーライド（例：契約社員や緊急アカウント）と、アトミックなデプロビジョニングを処理します。API 経由で直接作成されたユーザーは `scim_managed: false` を保持します。

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

サービスアカウントは、CI/CD パイプライン、IaC ツール、Terraform 自動化のためのマシン ID です。サービスアカウントは SCIM 所有ではなく、作成時に返される `client_id` を使用して OAuth 2.0 クライアント認証情報で認証します。

## アクセスモデル

プリンシパルの実効アクセスは、以下の独立したソースの和集合です：

* **直接のロール割り当て**– ユーザーまたはサービスアカウントに個別に割り当てられます（[ユーザーにロールを割り当て](/ja/API/Assign-User-Role) またはサービスアカウントの同等エンドポイントを介して）。
* **グループ由来のロール割り当て**– SCIM グループのメンバーシップから継承されます（ユーザーのみ）。
* **直接の権限**– リソースレベルの付与を個別に割り当てます（[ユーザーに権限を割り当て](/ja/API/Assign-User-Permission) またはサービスアカウントの同等エンドポイントを介して）。

### ロール

Connect AI には 2 種類のロールがあります：

| 種類            | 説明                        |
| :------------ | :------------------------ |
| `system_role` | 組み込みで変更不可。固定の機能セットを定義します。 |
| `access_role` | 明示的なリソースレベルの権限を持つカスタムロール。 |

アカウント全体の `admin` システムロールは、`POST /users/{id}/roles` または `POST /service-accounts/{id}/roles` を介して割り当てられます。

<Note>
  カスタムロールの管理（アクセスロールの作成、更新、削除）は、Management API ではまだ利用できません。
</Note>

### 組み込みシステムロール

| ロール                | スコープ    | 説明                                                                     |
| :----------------- | :------ | :--------------------------------------------------------------------- |
| `admin`            | アカウント全体 | 組織全体に対する完全な管理制御。                                                       |
| `workspace_admin`  | ワークスペース | ワークスペースの完全な制御：そのワークスペース内で `connection_admin` と `user_admin` を組み合わせたもの。 |
| `connection_admin` | ワークスペース | ワークスペース内のコネクションを管理。                                                    |
| `user_admin`       | ワークスペース | ワークスペース内のユーザーを管理。                                                      |
| `query`            | ワークスペース | ワークスペース内のコネクションに対するクエリを実行。                                             |
| `oem_admin`        | ワークスペース | ワークスペース内の OEM 管理。                                                      |
| `oem_viewer`       | ワークスペース | ワークスペース内の OEM 読み取りアクセス。                                                |
| `service_user`     | ワークスペース | ワークスペース内のサービスレベルアクセス。                                                  |

<Note>
  ワークスペーススコープのロール割り当てエンドポイントはまだ利用できません。現在、Management API 経由で割り当てられるのはアカウント全体の `admin` ロールのみです。
</Note>