グループ API

グループ API は、機能アクセス管理のためにメンバーを整理する際に使用します。1 人のメンバーは複数のグループに所属できます。グループメンバーシップは、メンバーのロール、シート、個人使用量上限、課金グループ、Credits 帰属を変更しません。

対象プラン：Enterprise。組織でグループ機能が有効になっている必要があります。

呼び出す前に API キーの取得を完了し、OpenAPI 共通仕様を確認してください。

前提条件

Authorization: Bearer <api_key> を送信します。
JSON リクエストボディがある場合は Content-Type: application/json を送信します。
API キーに紐づく組織を organization_id に指定します。
userIds リクエストフィールドには、組織メンバー ID ではなくユーザー ID を使用します。メンバー APIが返す userId フィールドから取得できます。

グループの種類

書き込み可否は source で判断します。source: "manual" のグループは Qoder で管理され、この API から更新、削除、メンバー変更ができます。その他のソースは OpenAPI では読み取り専用で、isManaged: true を返します。たとえば SCIM グループは source: "scim" を返します。読み取り専用グループは同期元システムで管理してください。

データモデル

Group

フィールド	型	説明
`id`	string	グループ ID
`organizationId`	string	組織 ID
`displayName`	string	グループ名
`description`	string	説明。空の場合は省略
`source`	string	`manual`、`scim` などのグループソース
`externalId`	string	同期元システムのグループ ID。空の場合は省略
`syncType`	string	`scim` などの同期タイプ。空の場合は省略
`isManaged`	boolean	メンバーシップが外部ソースで管理されているか
`creatorId`	string	作成者のユーザー ID。取得できない場合は省略
`createdAt`	string	作成日時（ISO 8601）。取得できない場合は省略
`updatedAt`	string	最終更新日時（ISO 8601）。取得できない場合は省略
`memberCount`	integer	現在のグループメンバー数

グループメンバー

フィールド	型	説明
`id`	string	組織メンバー ID
`userId`	string	ユーザー ID。グループメンバーの追加・削除時に使用
`name`	string	メンバー名
`email`	string	メールアドレス。取得できない場合は省略
`status`	string	`ENABLED`、`DISABLED` などの組織メンバーステータス
`joinedAt`	string	ユーザーが組織に参加した日時。取得できない場合は省略
`usageLimit`	object	現在の個人使用量上限。取得できない場合は省略
`usageLimit.quotaKey`	string	クォータ識別子
`usageLimit.limitValue`	number	上限値。`-1` は無制限
`usageLimit.usedValue`	number	現在の期間での使用量
`usageLimit.resetCycle`	string	リセット周期。取得できない場合は省略
`usageLimit.isActive`	boolean	上限が有効かどうか
`usageLimit.lastResetAt`	string	前回のリセット日時。取得できない場合は省略
`usageLimit.nextResetAt`	string	次回のリセット日時。取得できない場合は省略

グループメンバーオブジェクトには、メンバーのロールや課金グループは含まれません。これらのフィールドが必要な場合はメンバー APIを使用してください。

API リファレンス

グループ一覧

GET /v1/organizations/{organization_id}/groups

クエリパラメーター	型	必須	説明
`source`	string	いいえ	`manual`、`scim` などのソースを完全一致で絞り込み
`externalId`	string	いいえ	外部グループ ID を完全一致で絞り込み
`syncType`	string	いいえ	同期タイプを完全一致で絞り込み
`userId`	string	いいえ	指定したユーザー UUID を含むグループのみ返す
`keyword`	string	いいえ	グループ名または説明を大文字・小文字を区別せず検索
`maxResults`	integer	いいえ	ページサイズ。デフォルト 20、最大 100
`nextToken`	string	いいえ	前回のレスポンスで返されたカーソル

成功レスポンス（200 OK）

{
  "groups": [
    {
      "id": "1c8f3ee2-b970-4b61-93f9-f8be080ae945",
      "organizationId": "org_xxx",
      "displayName": "Platform Team",
      "description": "Platform maintainers",
      "source": "manual",
      "isManaged": false,
      "creatorId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-08-01T08:00:00Z",
      "updatedAt": "2026-08-01T08:00:00Z",
      "memberCount": 2
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

最終ページでは nextToken が省略されます。

グループの作成

POST /v1/organizations/{organization_id}/groups 手動管理グループを作成します。displayName は前後の空白が除去され、空にはできません。有効な既存の手動グループと同じ名前は使用できません。userIds を省略するか空配列を送信すると、メンバーなしで作成できます。重複ユーザー ID は除外されます。ID が 1 つでも無効、または現在の組織メンバーでない場合、リクエストは失敗し、グループは作成されません。

リクエストボディ

{
  "displayName": "Platform Team",
  "description": "Platform maintainers",
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

フィールド	型	必須	説明
`displayName`	string	はい	グループ名
`description`	string	いいえ	グループの説明
`userIds`	string 配列	いいえ	グループ作成時に追加するユーザー UUID。1 リクエストあたり最大 100 件

作成された Group を 201 Created で返します。

グループの取得

GET /v1/organizations/{organization_id}/groups/{group_id} 指定した Group を 200 OK で返します。

グループの更新

PUT /v1/organizations/{organization_id}/groups/{group_id} 手動管理グループのみ更新できます。省略したフィールドは変更されません。空の description を送信すると説明を消去できます。

リクエストボディ

{
  "displayName": "Platform Engineering",
  "description": ""
}

フィールド	型	必須	説明
`displayName`	string	いいえ	新しいグループ名。前後の空白を除去した後に空にはできません
`description`	string	いいえ	新しい説明。空文字列で消去

更新された Group を 200 OK で返します。

グループの削除

DELETE /v1/organizations/{organization_id}/groups/{group_id} 手動管理グループのみ削除できます。グループを削除すると、メンバーシップとグループに紐づくアクセスポリシーが削除されます。組織メンバーは削除されず、課金グループ、個人使用量上限、履歴使用量も変更されません。 200 OK を返します：

{}

グループメンバー一覧

GET /v1/organizations/{organization_id}/groups/{group_id}/members

クエリパラメーター	型	必須	説明
`keyword`	string	いいえ	メンバー名またはメールアドレスを大文字・小文字を区別せず検索
`maxResults`	integer	いいえ	ページサイズ。デフォルト 20、最大 100
`nextToken`	string	いいえ	前回のレスポンスで返されたカーソル

成功レスポンス（200 OK）

{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice",
      "email": "alice@example.com",
      "status": "ENABLED",
      "joinedAt": "2026-06-01T08:00:00Z",
      "usageLimit": {
        "quotaKey": "big_model_credits",
        "limitValue": 5000,
        "usedValue": 1250,
        "resetCycle": "monthly",
        "isActive": true
      }
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

最終ページでは nextToken が省略されます。

グループメンバーの追加

POST /v1/organizations/{organization_id}/groups/{group_id}/members 1 人以上の組織ユーザーを手動管理グループに追加します。既存のメンバーシップは重複して作成されません。

リクエストボディ

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

userIds は必須で、空でないユーザー ID を 1 リクエストあたり 1～100 件指定します。重複または追加済みのユーザー ID から重複メンバーシップは作成されません。メンバーシップを変更する前にすべての ID が検証されます。ID が 1 つでも不正、または現在の組織メンバーでない場合、リクエストは 400 BadRequest で失敗し、メンバーシップは追加されません。 200 OK レスポンスには現在のグループメンバーが先頭から最大 20 人含まれ、ページネーションフィールドはありません。完全な一覧にはグループメンバー一覧を使用してください。

{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice",
      "email": "alice@example.com",
      "status": "ENABLED",
      "joinedAt": "2026-06-01T08:00:00Z"
    }
  ]
}

グループメンバーの削除

DELETE /v1/organizations/{organization_id}/groups/{group_id}/members 手動管理グループから 1 つ以上のメンバーシップを削除します。ユーザー自体は組織から削除されません。

リクエストボディ

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

userIds は必須で、空でないユーザー ID を 1 リクエストあたり 1～100 件指定します。この API は DELETE に JSON ボディを使用するため、HTTP クライアントとプロキシがボディを保持することを確認してください。ID が 1 つでも不正な場合、リクエストは 400 BadRequest で失敗し、メンバーシップは削除されません。有効な ID でも組織メンバーでない、またはグループにいない場合は何も変更されず、同じリクエスト内の他の一致するメンバーシップは削除されます。200 OK を返します：

{}

エラー

エラーは OpenAPI 共通仕様で説明する標準レスポンス形式を使用します。

HTTP ステータス	エラーコード	主な原因
400	`BadRequest`	不正なリクエスト、ID、カーソル、または空の必須フィールド
400	`OrganizationGroupSCIMReadOnly`	同期または外部管理グループを変更しようとした
401	`Unauthorized`	API キーがない、または無効
403	`Forbidden`	API キーが対象組織に属していない
403	`OrganizationPlanCapabilityForbidden`	組織でグループ機能が有効でない
404	`NotFound`	グループまたはメンバーが存在しない
409	`AlreadyExists`	同名の有効な手動グループがすでに存在する

​前提条件

​グループの種類

​データモデル

​Group

​グループメンバー

​API リファレンス

​グループ一覧

​成功レスポンス（200 OK）

​グループの作成

​リクエストボディ

​グループの取得

​グループの更新

​リクエストボディ

​グループの削除

​グループメンバー一覧

​成功レスポンス（200 OK）

​グループメンバーの追加

​リクエストボディ

​グループメンバーの削除

​リクエストボディ

​エラー

前提条件

グループの種類

データモデル

Group

グループメンバー

API リファレンス

グループ一覧

成功レスポンス（200 OK）

グループの作成

リクエストボディ

グループの取得

グループの更新

リクエストボディ

グループの削除

グループメンバー一覧

成功レスポンス（200 OK）

グループメンバーの追加

リクエストボディ

グループメンバーの削除

リクエストボディ

エラー