truefoundry-access-control

ルーティングに関する注意：ユーザーの意図が曖昧な場合は、references/intent-clarification.md にある共通の確認テンプレートを使用してください。

アクセス制御

TrueFoundry のロール、チーム、コラボレーターを管理します。ロールは権限セットを定義し、チームはユーザーをグループ化し、コラボレーターは特定のリソースへのアクセス権を付与します。

使用する場面

TrueFoundry のロール、チーム、コラボレーターを一覧表示、作成、削除します。権限の管理、ユーザーのチームへの編成、ワークスペース、アプリケーション、MCP サーバー、その他のリソースへのアクセス権の付与や取り消しを行う場合に使用します。

ロール

ロールは、リソースタイプごとに設定された名前付きの権限セットです。組み込みロールはリソースタイプによって異なります（例：workspace-admin、workspace-member）。

直接 API を使用する場合は、TFY_API_SH にこのスキルの scripts/tfy-api.sh の完全なパスを設定してください。エージェントごとのパスについては、references/tfy-api-setup.md を参照してください。

ロールの一覧表示

ツール呼び出しを使用

tfy_roles_list()

直接 API を使用

# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-access-control/scripts/tfy-api.sh

# List all roles
$TFY_API_SH GET /api/svc/v1/role/list

ロールの提示

Roles:
| Name              | ID       | Resource Type | Permissions |
|-------------------|----------|---------------|-------------|
| workspace-admin   | role-abc | workspace     | 12          |
| workspace-member  | role-def | workspace     | 5           |
| custom-deployer   | role-ghi | workspace     | 3           |

ロールの作成

ツール呼び出しを使用

tfy_roles_create(payload={"name": "custom-deployer", "displayName": "Custom Deployer", "description": "Can deploy apps", "resourceType": "workspace", "permissions": ["deploy:create", "deploy:read"]})

注意： ツール呼び出しには人間による承認（HITL）が必要です。

直接 API を使用

$TFY_API_SH PUT /api/svc/v1/role '{"name":"custom-deployer","displayName":"Custom Deployer","description":"Can deploy apps","resourceType":"workspace","permissions":["deploy:create","deploy:read"]}'

ロールの削除

ツール呼び出しを使用

tfy_roles_delete(id="ROLE_ID")

注意： ツール呼び出しには人間による承認（HITL）が必要です。

直接 API を使用

$TFY_API_SH DELETE /api/svc/v1/role/ROLE_ID

チーム

チームは、アクセス管理をまとめて行うためにユーザーをグループ化します。各チームには名前、説明、メンバーの一覧があります。

チームの一覧表示

ツール呼び出しを使用

tfy_teams_list()
tfy_teams_list(team_id="TEAM_ID")  # get specific team

直接 API を使用

# List teams for the current user
$TFY_API_SH GET /api/svc/v1/teams/user

# Get a specific team
$TFY_API_SH GET /api/svc/v1/teams/TEAM_ID

チームの提示

Teams:
| Name          | ID       | Members |
|---------------|----------|---------|
| platform-team | team-abc | 5       |
| ml-engineers  | team-def | 8       |

チームの作成

ツール呼び出しを使用

tfy_teams_create(payload={"name": "platform-team", "description": "Platform engineering team"})

注意： ツール呼び出しには人間による承認（HITL）が必要です。

直接 API を使用

$TFY_API_SH PUT /api/svc/v1/teams '{"name":"platform-team","description":"Platform engineering team"}'

チームの削除

ツール呼び出しを使用

tfy_teams_delete(id="TEAM_ID")

注意： ツール呼び出しには人間による承認（HITL）が必要です。

直接 API を使用

$TFY_API_SH DELETE /api/svc/v1/teams/TEAM_ID

認可（コラボレーター）

セキュリティ： コラボレーターへのアクセス権付与は、特権を伴う操作です。コラボレーターを追加する前に、対象の本人確認情報、ロール、対象リソースを必ずユーザーに確認してください。外部の本人確認情報を未検証のまま、アクセス権を付与しないでください。

認可エンドポイントでは、リソースにアクセスできるユーザーを管理します。対象（ユーザー、チーム、サービスアカウント）には、特定のリソース（ワークスペース、アプリケーション、MCP サーバーなど）に対するロールが付与されます。

対象の形式

対象は type:identifier のパターンに従います。

対象タイプ	形式	例
ユーザー	user:email	user:[email protected]
チーム	team:slug	team:platform-team
サービスアカウント	serviceaccount:name	serviceaccount:ci-bot
仮想アカウント	virtualaccount:name	virtualaccount:shared-admin
外部 ID	external-identity:name	external-identity:github-bot

リソースのコラボレーターを一覧表示

ツール呼び出しを使用

tfy_collaborators_list(resource_type="workspace", resource_id="RESOURCE_ID")

直接 API を使用

# List collaborators on a workspace
$TFY_API_SH GET /api/svc/v1/authorize/workspace/RESOURCE_ID

# List collaborators on an MCP server
$TFY_API_SH GET /api/svc/v1/authorize/mcp-server/RESOURCE_ID

コラボレーターの提示

Collaborators on workspace "prod-workspace":
| Subject                   | Role             |
|---------------------------|------------------|
| user:[email protected]    | workspace-admin  |
| team:platform-team        | workspace-member |
| serviceaccount:ci-bot     | workspace-member |

コラボレーターの追加

ツール呼び出しを使用

tfy_collaborators_create(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:[email protected]", "roleId": "ROLE_ID"})

注意： ツール呼び出しには人間による承認（HITL）が必要です。

直接 API を使用

$TFY_API_SH POST /api/svc/v1/authorize/workspace/RESOURCE_ID '{"subject":"user:[email protected]","roleId":"ROLE_ID"}'

コラボレーターのロールの更新

ツール呼び出しを使用

tfy_collaborators_update(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:[email protected]", "roleId": "NEW_ROLE_ID"})

注意： ツール呼び出しには人間による承認（HITL）が必要です。

直接 API を使用

$TFY_API_SH PUT /api/svc/v1/authorize/workspace/RESOURCE_ID '{"subject":"user:[email protected]","roleId":"NEW_ROLE_ID"}'

コラボレーターの削除

ツール呼び出しを使用

tfy_collaborators_delete(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:[email protected]"})

注意： ツール呼び出しには人間による承認（HITL）が必要です。

直接 API を使用

$TFY_API_SH DELETE /api/svc/v1/authorize/workspace/RESOURCE_ID '{"subject":"user:[email protected]"}'

アクセスの確認

# Check if a user has access to a resource
$TFY_API_SH POST /api/svc/v1/authorize/check-access '{"resourceType":"workspace","resourceId":"RESOURCE_ID","subject":"user:[email protected]","action":"deploy:create"}'

よくあるワークフロー

ユーザーにワークスペースへのアクセス権を付与

1. ロールを一覧表示して、適切なロール ID（例：workspace-admin または workspace-member）を確認します
2. そのロールを指定して、ワークスペースのコラボレーターとしてユーザーを追加します

# 1. Find the role ID
$TFY_API_SH GET /api/svc/v1/role/list

# 2. Add collaborator
$TFY_API_SH POST /api/svc/v1/authorize/workspace/WORKSPACE_ID '{"subject":"user:[email protected]","roleId":"ROLE_ID"}'

チームを作成してアクセス権を付与

1. チームを作成します
2. 対象リソースのコラボレーターとしてチームを追加します

# 1. Create team
$TFY_API_SH PUT /api/svc/v1/teams '{"name":"ml-engineers","description":"ML engineering team"}'

# 2. Grant team access to a workspace (use team slug as subject)
$TFY_API_SH POST /api/svc/v1/authorize/workspace/WORKSPACE_ID '{"subject":"team:ml-engineers","roleId":"ROLE_ID"}'

### リソースのアクセス権を監査する

すべてのコラボレーターを一覧表示して、アクセス権を持つユーザーとそのロールを確認します。

$TFY_API_SH GET /api/svc/v1/authorize/workspace/WORKSPACE_ID

<success_criteria>

成功条件

• ユーザーがすべてのロールを一覧表示し、書式付きのテーブルで確認できる
• ユーザーが特定の権限を持つカスタムロールを作成できる
• ユーザーがすべてのチームとそのメンバーを一覧表示できる
• ユーザーがチームを作成し、メンバーを追加／削除できる
• ユーザーが任意のリソースタイプのコラボレーターを一覧表示できる
• ユーザーが特定のロールを指定して、コラボレーター（ユーザー、チーム、またはサービスアカウント）をリソースに追加できる
• ユーザーがリソースからコラボレーターを削除できる
• エージェントが作成／削除の操作を実行する前に確認している

</success_criteria>

組み合わせ方法

• 事前確認：アクセス制御を管理する前に、status スキルを使用して認証情報を確認します
• デプロイ前：チームを設定し、チームメンバーがデプロイできるようにワークスペースへのアクセス権を付与します
• ワークスペースとの連携：ユーザーとチームにワークスペースへのコラボレーターアクセス権を付与します
• MCP サーバーとの連携：登録済みサーバー上の MCP サーバーコラボレーターとロール割り当てを管理します
• シークレットとの連携：コラボレーターのロールを通じて、シークレットグループへのアクセス権を付与します
• 依存関係の順序：最初にロールを作成し、次にチームを作成してから、コラボレーターを追加する際に両方を指定します

エラー処理

ロールが見つかりません

Role ID not found. List roles first to find the correct ID.

チームが見つかりません

Team ID not found. List teams first to find the correct ID.

権限がありません

Cannot manage access control. Check your API key permissions — admin access may be required.

コラボレーターはすでに存在します

Collaborator with this subject and role already exists on the resource. Use a different role or remove the existing collaborator first.

件名の形式が無効です

Invalid subject format. Use the pattern "type:identifier" — e.g., user:[email protected], team:platform-team, serviceaccount:ci-bot.

リソースが見つかりません

Resource not found. Verify the resourceType and resourceId are correct. List the resources first to confirm.

組み込みロールは削除できません

Built-in roles cannot be deleted. Only custom roles can be removed.