EndUserロール管理

概要

EndUserロール管理APIは、RBAC（Role-Based Access Control）を実装するためのエンドポイントを提供します。ロールの定義、エンドユーザーやグループへの割り当て、権限の管理が可能です。

エンドポイント一覧

メソッド	エンドポイント	説明
GET	`/api/admin/roles`	ロール一覧取得
GET	`/api/admin/roles/:id`	ロール詳細取得
POST	`/api/admin/roles`	ロール作成
PUT	`/api/admin/roles/:id`	ロール更新
DELETE	`/api/admin/roles/:id`	ロール削除
GET	`/api/admin/users/:id/roles`	ユーザーのロール一覧取得
POST	`/api/admin/users/:id/roles`	ユーザーにロール割り当て
DELETE	`/api/admin/users/:id/roles/:roleId`	ユーザーからロール削除

ロール一覧取得

テナント内のロール一覧を取得します。

エンドポイント

GET /api/admin/roles

クエリパラメータ

パラメータ	型	必須	説明
`limit`	integer	-	取得件数（デフォルト: 20、最大: 100）
`cursor`	string	-	ページネーションカーソル
`search`	string	-	名前で検索
`type`	string	-	ロールタイプでフィルタ（`system`, `custom`）

リクエスト例

curl -X GET "https://{tenant-domain}/api/admin/roles" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "items": [
    {
      "id": "role_admin",
      "name": "admin",
      "display_name": "管理者",
      "description": "テナント管理者ロール",
      "type": "system",
      "permissions": ["users:*", "clients:*", "settings:*"],
      "user_count": 5,
      "created_at": 1705881600,
      "updated_at": 1705881600
    },
    {
      "id": "role_editor",
      "name": "editor",
      "display_name": "編集者",
      "description": "コンテンツ編集権限",
      "type": "custom",
      "permissions": ["content:read", "content:write"],
      "user_count": 20,
      "created_at": 1705968000,
      "updated_at": 1706054400
    }
  ],
  "total": 10,
  "cursor": null
}

ロール詳細取得

指定されたロールの詳細情報を取得します。

エンドポイント

GET /api/admin/roles/:id

パスパラメータ

パラメータ	型	必須	説明
`id`	string	○	ロールID

リクエスト例

curl -X GET "https://{tenant-domain}/api/admin/roles/role_editor" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "id": "role_editor",
  "name": "editor",
  "display_name": "編集者",
  "description": "コンテンツ編集権限を持つロール",
  "type": "custom",
  "permissions": [
    "content:read",
    "content:write",
    "content:delete",
    "media:read",
    "media:upload"
  ],
  "inherits_from": ["role_viewer"],
  "user_count": 20,
  "metadata": {
    "department": "Marketing"
  },
  "created_at": 1705968000,
  "updated_at": 1706054400
}

ロール作成

新しいロールを作成します。

エンドポイント

POST /api/admin/roles

リクエストボディ

フィールド	型	必須	説明
`name`	string	○	ロール名（英数字、ハイフン、アンダースコア）
`display_name`	string	○	表示名
`description`	string	-	説明
`permissions`	string[]	○	権限リスト
`inherits_from`	string[]	-	継承元ロールID
`metadata`	object	-	カスタムメタデータ

リクエスト例

curl -X POST "https://{tenant-domain}/api/admin/roles" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "content_manager",
    "display_name": "コンテンツマネージャー",
    "description": "コンテンツの管理権限",
    "permissions": [
      "content:read",
      "content:write",
      "content:delete",
      "content:publish"
    ],
    "inherits_from": ["role_viewer"]
  }'

レスポンス例

{
  "id": "role_content_manager",
  "name": "content_manager",
  "display_name": "コンテンツマネージャー",
  "type": "custom",
  "permissions": [
    "content:read",
    "content:write",
    "content:delete",
    "content:publish"
  ],
  "inherits_from": ["role_viewer"],
  "created_at": 1706140800
}

ロール更新

既存のロール設定を更新します。

エンドポイント

PUT /api/admin/roles/:id

リクエスト例

curl -X PUT "https://{tenant-domain}/api/admin/roles/role_editor" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "上級編集者",
    "permissions": [
      "content:read",
      "content:write",
      "content:delete",
      "content:publish",
      "content:archive"
    ]
  }'

ロール削除

ロールを削除します。

エンドポイント

DELETE /api/admin/roles/:id

リクエスト例

curl -X DELETE "https://{tenant-domain}/api/admin/roles/role_editor" \
  -H "Authorization: Bearer {token}"

レスポンス

ステータスコード 204 No Content（ボディなし）

ユーザーのロール一覧取得

指定されたユーザーに割り当てられているロール一覧を取得します。

エンドポイント

GET /api/admin/users/:id/roles

パスパラメータ

パラメータ	型	必須	説明
`id`	string	○	ユーザーID

リクエスト例

curl -X GET "https://{tenant-domain}/api/admin/users/usr_abc123/roles" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "items": [
    {
      "id": "role_editor",
      "name": "editor",
      "display_name": "編集者",
      "assigned_at": 1705968000,
      "assigned_by": "usr_admin001",
      "scope": {
        "type": "global"
      }
    },
    {
      "id": "role_org_admin",
      "name": "org_admin",
      "display_name": "組織管理者",
      "assigned_at": 1706054400,
      "assigned_by": "usr_admin001",
      "scope": {
        "type": "organization",
        "organization_id": "org_abc123",
        "organization_name": "Engineering"
      }
    }
  ]
}

ユーザーにロール割り当て

ユーザーにロールを割り当てます。

エンドポイント

POST /api/admin/users/:id/roles

パスパラメータ

パラメータ	型	必須	説明
`id`	string	○	ユーザーID

リクエストボディ

フィールド	型	必須	説明
`role_id`	string	○	ロールID
`scope`	object	-	スコープ（組織限定の場合）

リクエスト例（グローバルスコープ）

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/roles" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "role_editor"
  }'

リクエスト例（組織スコープ）

curl -X POST "https://{tenant-domain}/api/admin/users/usr_abc123/roles" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "role_org_admin",
    "scope": {
      "type": "organization",
      "organization_id": "org_abc123"
    }
  }'

レスポンス例

{
  "user_id": "usr_abc123",
  "role_id": "role_editor",
  "assigned_at": 1706140800,
  "assigned_by": "usr_admin001"
}

ユーザーからロール削除

ユーザーからロールの割り当てを解除します。

エンドポイント

DELETE /api/admin/users/:id/roles/:roleId

パスパラメータ

パラメータ	型	必須	説明
`id`	string	○	ユーザーID
`roleId`	string	○	ロールID

クエリパラメータ

パラメータ	型	必須	説明
`organization_id`	string	-	組織スコープの場合、組織ID

リクエスト例

curl -X DELETE "https://{tenant-domain}/api/admin/users/usr_abc123/roles/role_editor" \
  -H "Authorization: Bearer {token}"

レスポンス

ステータスコード 204 No Content（ボディなし）

権限の書式

権限は resource:action の形式で指定します。

ワイルドカード

users:* - usersリソースに対するすべてのアクション
*:read - すべてのリソースに対する読み取り
*:* - すべての権限

一般的な権限例

権限	説明
`users:read`	ユーザー情報の読み取り
`users:write`	ユーザーの作成・更新
`users:delete`	ユーザーの削除
`clients:read`	クライアント情報の読み取り
`clients:write`	クライアントの作成・更新
`settings:read`	設定の読み取り
`settings:write`	設定の変更
`audit:read`	監査ログの読み取り