truefoundry-access-control

路由说明：对于含义不明确的用户意图，请使用 references/intent-clarification.md 中的通用澄清模板。

访问控制

管理 TrueFoundry 角色、团队和协作者。角色定义权限集，团队用于对用户进行分组，协作者则授予对特定资源的访问权限。

适用场景

在 TrueFoundry 上列出、创建或删除角色、团队和协作者。在管理权限、将用户组织到团队中，或授予／撤销对工作区、应用程序、MCP 服务或其他资源的访问权限时使用。

角色

角色是限定于某种资源类型的命名权限集。内置角色因资源类型而异（例如，workspace-admin、workspace-member）。

使用直接 API 时，将 TFY_API_SH 设置为此技能的 scripts/tfy-api.sh 的完整路径。不同 Agent 的路径请参阅 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
外部身份	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>

成功标准

• 用户可以列出所有角色，并以格式化表格查看
• 用户可以创建具有特定权限的自定义角色
• 用户可以列出所有团队及其成员
• 用户可以创建团队并添加或移除成员
• 用户可以列出任何资源类型的协作者
• 用户可以为资源添加协作者（用户、团队或服务账号），并指定角色
• 用户可以从资源中移除协作者
• 执行任何创建或删除操作前，Agent 已确认

</success_criteria>

组合使用

• 预检：在管理访问控制前，使用 status skill 验证凭据
• 部署前：设置团队并授予工作区访问权限，以便团队成员可以部署
• 配合工作区使用：为用户和团队授予工作区协作者访问权限
• 配合 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.