truefoundry-access-control

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.

路由提示：若遇到用户意图不明确的情况，请使用references/intent-clarification.md中提供的通用澄清模板。

Access Control

访问控制

Manage TrueFoundry roles, teams, and collaborators. Roles define permission sets, teams group users, and collaborators grant access to specific resources.

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

When to Use

适用场景

List, create, or delete roles, teams, and collaborators on TrueFoundry. Use when managing permissions, organizing users into teams, or granting/revoking access to workspaces, applications, MCP servers, or other resources.

</objective> <instructions>

列举、创建或删除TrueFoundry上的角色、团队与协作者。适用于管理权限、将用户组织为团队，或是授予/收回工作空间、应用、MCP服务器或其他资源访问权限的场景。

</objective> <instructions>

Roles

角色

Roles are named permission sets scoped to a resource type. Built-in roles vary by resource type (for example,

workspace-admin

workspace-member

When using direct API, set

TFY_API_SH

to the full path of this skill's

scripts/tfy-api.sh

. See

references/tfy-api-setup.md

for paths per agent.

角色是绑定到特定资源类型的命名权限集合。内置角色随资源类型不同而有所区别（例如

workspace-admin

、

workspace-member

）。

使用直接API调用时，请将

TFY_API_SH

设置为该技能

scripts/tfy-api.sh

文件的完整路径。各Agent对应的路径可查看

references/tfy-api-setup.md

文档。

List Roles

列举角色

Via Tool Call

通过工具调用

tfy_roles_list()

tfy_roles_list()

Via Direct API

通过直接API

bash

undefined

bash

undefined

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/roles

undefined

$TFY_API_SH GET /api/svc/v1/roles

undefined

Presenting Roles

角色展示格式

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

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

Create Role

创建角色

Via Tool Call

通过工具调用

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

Note: Requires human approval (HITL) via tool call.

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

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

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

bash

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

Delete Role

删除角色

Via Tool Call

通过工具调用

tfy_roles_delete(id="ROLE_ID")

Note: Requires human approval (HITL) via tool call.

tfy_roles_delete(id="ROLE_ID")

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

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

bash

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

Teams

团队

Teams group users for collective access management. Each team has a name, description, and members list.

团队用于对用户进行分组，实现批量权限管理。每个团队包含名称、描述和成员列表。

List Teams

列举团队

Via Tool Call

通过工具调用

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

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

Via Direct API

通过直接API

bash

undefined

bash

undefined

List all teams

$TFY_API_SH GET /api/svc/v1/teams

Get a specific team

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

undefined

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

undefined

Presenting Teams

团队展示格式

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

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

Create Team

创建团队

Via Tool Call

通过工具调用

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

Note: Requires human approval (HITL) via tool call.

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

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

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

bash

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

Delete Team

删除团队

Via Tool Call

通过工具调用

tfy_teams_delete(id="TEAM_ID")

Note: Requires human approval (HITL) via tool call.

tfy_teams_delete(id="TEAM_ID")

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

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

bash

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

Add Member to Team

添加团队成员

Via Tool Call

通过工具调用

tfy_teams_add_member(team_id="TEAM_ID", payload={"subject": "user:alice@company.com", "role": "member"})

Note: Requires human approval (HITL) via tool call.

tfy_teams_add_member(team_id="TEAM_ID", payload={"subject": "user:alice@company.com", "role": "member"})

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

$TFY_API_SH POST /api/svc/v1/teams/TEAM_ID/members '{"subject":"user:alice@company.com","role":"member"}'

bash

$TFY_API_SH POST /api/svc/v1/teams/TEAM_ID/members '{"subject":"user:alice@company.com","role":"member"}'

Remove Member from Team

移除团队成员

Via Tool Call

通过工具调用

tfy_teams_remove_member(team_id="TEAM_ID", subject="user:alice@company.com")

Note: Requires human approval (HITL) via tool call.

tfy_teams_remove_member(team_id="TEAM_ID", subject="user:alice@company.com")

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

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

bash

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

Example SUBJECT: user:alice@company.com

undefined

undefined

Collaborators

协作者

Security: Granting collaborator access is a privileged operation. Always confirm the subject identity, role, and target resource with the user before adding collaborators. Do not grant access based on unverified external identity references.

Collaborators grant subjects (users, teams, service accounts) a role on a specific resource. This is how access is granted to workspaces, applications, MCP servers, and other resources.

安全提示： 授予协作者访问权限是高权限操作。添加协作者前，请务必与用户确认主体身份、角色和目标资源。请勿基于未经验证的外部身份引用授予访问权限。

协作者机制用于为主体（用户、团队、服务账户）授予特定资源的对应角色。这是为工作空间、应用、MCP服务器及其他资源授予访问权限的实现方式。

Subject Format

主体格式

Subjects follow the pattern

type:identifier

Subject Type	Format	Example
User	`user:email`	`user:alice@company.com`
Team	`team:slug`	`team:platform-team`
Service Account	`serviceaccount:name`	`serviceaccount:ci-bot`
Virtual Account	`virtualaccount:name`	`virtualaccount:shared-admin`
External Identity	`external-identity:name`	`external-identity:github-bot`

主体遵循

类型:标识符

的命名规则：

主体类型	格式	示例
用户	`user:email`	`user:alice@company.com`
团队	`team:slug`	`team:platform-team`
服务账户	`serviceaccount:name`	`serviceaccount:ci-bot`
虚拟账户	`virtualaccount:name`	`virtualaccount:shared-admin`
外部身份	`external-identity:name`	`external-identity:github-bot`

List Collaborators on a Resource

列举资源的协作者

Via Tool Call

通过工具调用

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

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

Via Direct API

通过直接API

bash

undefined

bash

undefined

List collaborators on a workspace

$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=workspace&resourceId=RESOURCE_ID'

List collaborators on an MCP server

$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=mcp-server&resourceId=RESOURCE_ID'

undefined

$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=mcp-server&resourceId=RESOURCE_ID'

undefined

Presenting Collaborators

协作者展示格式

Collaborators on workspace "prod-workspace":
| Subject                   | Role             | ID       |
|---------------------------|------------------|----------|
| user:alice@company.com    | workspace-admin  | collab-1 |
| team:platform-team        | workspace-member | collab-2 |
| serviceaccount:ci-bot     | workspace-member | collab-3 |

Collaborators on workspace "prod-workspace":
| Subject                   | Role             | ID       |
|---------------------------|------------------|----------|
| user:alice@company.com    | workspace-admin  | collab-1 |
| team:platform-team        | workspace-member | collab-2 |
| serviceaccount:ci-bot     | workspace-member | collab-3 |

Add Collaborator

添加协作者

Via Tool Call

通过工具调用

tfy_collaborators_create(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:alice@company.com", "roleId": "ROLE_ID"})

Note: Requires human approval (HITL) via tool call.

tfy_collaborators_create(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:alice@company.com", "roleId": "ROLE_ID"})

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"RESOURCE_ID","subject":"user:alice@company.com","roleId":"ROLE_ID"}'

bash

$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"RESOURCE_ID","subject":"user:alice@company.com","roleId":"ROLE_ID"}'

Remove Collaborator

移除协作者

Via Tool Call

通过工具调用

tfy_collaborators_delete(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:alice@company.com"})

Note: Requires human approval (HITL) via tool call.

tfy_collaborators_delete(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:alice@company.com"})

注意： 工具调用需要经过人工审批（HITL）。

Via Direct API

通过直接API

bash

$TFY_API_SH DELETE /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"RESOURCE_ID","subject":"user:alice@company.com"}'

bash

$TFY_API_SH DELETE /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"RESOURCE_ID","subject":"user:alice@company.com"}'

Common Workflows

常用工作流

Grant a User Access to a Workspace

授予用户工作空间访问权限

List roles to find the appropriate role ID (e.g.,
```
workspace-admin
```
or
```
workspace-member
```
)
Add the user as a collaborator on the workspace with that role

bash

undefined

列举角色找到对应的角色ID（例如
```
workspace-admin
```
或
```
workspace-member
```
）
将用户添加为该工作空间的协作者并分配对应角色

bash

undefined

1. Find the role ID

1. 查找角色ID

$TFY_API_SH GET /api/svc/v1/roles

2. Add collaborator

2. 添加协作者

$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"WORKSPACE_ID","subject":"user:alice@company.com","roleId":"ROLE_ID"}'

undefined

$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"WORKSPACE_ID","subject":"user:alice@company.com","roleId":"ROLE_ID"}'

undefined

Create a Team and Grant Access

创建团队并授予访问权限

Create the team
Add members to the team
Add the team as a collaborator on the target resource

bash

undefined

创建团队
向团队中添加成员
将团队添加为目标资源的协作者

bash

undefined

1. Create team

1. 创建团队

$TFY_API_SH POST /api/svc/v1/teams '{"name":"ml-engineers","description":"ML engineering team"}'

2. Add members (use team ID from response)

2. 添加成员（使用响应返回的团队ID）

$TFY_API_SH POST /api/svc/v1/teams/TEAM_ID/members '{"subject":"user:alice@company.com","role":"member"}'

3. Grant team access to a workspace

3. 授予团队工作空间访问权限

$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"WORKSPACE_ID","subject":"team:ml-engineers","roleId":"ROLE_ID"}'

undefined

$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"WORKSPACE_ID","subject":"team:ml-engineers","roleId":"ROLE_ID"}'

undefined

Audit Access on a Resource

审计资源访问权限

List all collaborators to see who has access and with what role:

bash

$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=workspace&resourceId=WORKSPACE_ID'

</instructions>

<success_criteria>

列举所有协作者查看权限分配情况：

bash

$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=workspace&resourceId=WORKSPACE_ID'

</instructions>

<success_criteria>

Success Criteria

成功判定标准

The user can list all roles and see them in a formatted table
The user can create a custom role with specific permissions
The user can list all teams and their members
The user can create a team and add/remove members
The user can list collaborators on any resource type
The user can add a collaborator (user, team, or service account) to a resource with a specific role
The user can remove a collaborator from a resource
The agent has confirmed any create/delete operations before executing

</success_criteria>

用户可列举所有角色并查看格式化表格展示结果
用户可创建带有指定权限的自定义角色
用户可列举所有团队及其成员
用户可创建团队并添加/移除成员
用户可列举任意资源类型的协作者
用户可将协作者（用户、团队或服务账户）添加到资源并分配指定角色
用户可移除资源的协作者
Agent在执行任何创建/删除操作前已完成确认

</success_criteria>

Composability

组合使用说明

Preflight: Use
```
status
```
skill to verify credentials before managing access control
Before deploy: Set up teams and grant workspace access so team members can deploy
With workspaces: Grant collaborator access to workspaces for users and teams
With MCP servers: Manage MCP server collaborators and role assignments on registered servers
With secrets: Grant access to secret groups via collaborator roles
Dependency chain: Create roles first, then create teams, then reference both when adding collaborators

</references> <troubleshooting>

前置检查：管理访问控制前使用
```
status
```
技能验证凭证有效性
部署前操作：创建团队并授予工作空间访问权限，确保团队成员可执行部署操作
与工作空间配合：为用户和团队授予工作空间的协作者访问权限
与MCP服务器配合：管理已注册MCP服务器的协作者及角色分配
与密钥配合：通过协作者角色授予密钥组的访问权限
依赖顺序：先创建角色，再创建团队，最后在添加协作者时引用两者

</references> <troubleshooting>

Error Handling

错误处理

Role Not Found

角色未找到

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

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

Team Not Found

团队未找到

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

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

Permission Denied

权限被拒绝

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

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

Collaborator Already Exists

协作者已存在

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

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

Invalid Subject Format

主体格式无效

Invalid subject format. Use the pattern "type:identifier" — e.g., user:alice@company.com, team:platform-team, serviceaccount:ci-bot.

Invalid subject format. Use the pattern "type:identifier" — e.g., user:alice@company.com, team:platform-team, serviceaccount:ci-bot.

Resource Not Found

资源未找到

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

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

Cannot Delete Built-in Role

无法删除内置角色

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

</troubleshooting>

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

</troubleshooting>