truefoundry-access-control — truefoundry/tfy-deplo…

仓库原始内容

按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Routing note: For ambiguous user intents, use the shared clarification templates in 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.

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>

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.

List Roles

Via Tool Call

tfy_roles_list()

Via Direct API

bash

# 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

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           |

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.

Via Direct API

bash

$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"]}'

Delete Role

Via Tool Call

tfy_roles_delete(id="ROLE_ID")

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

Via Direct API

bash

$TFY_API_SH DELETE /api/svc/v1/role/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

Via Direct API

bash

# 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

Presenting Teams

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.

Via Direct API

bash

$TFY_API_SH PUT /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.

Via Direct API

bash

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

Authorization (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.

Authorization endpoints manage who has access to resources. Subjects (users, teams, service accounts) are granted roles on specific resources (workspaces, applications, MCP servers, etc.).

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`

List Collaborators on a Resource

Via Tool Call

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

Via Direct API

bash

# 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

Presenting Collaborators

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

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.

Via Direct API

bash

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

Update Collaborator Role

Via Tool Call

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

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

Via Direct API

bash

$TFY_API_SH PUT /api/svc/v1/authorize/workspace/RESOURCE_ID '{"subject":"user:alice@company.com","roleId":"NEW_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.

Via Direct API

bash

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

Check Access

bash

# 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:alice@company.com","action":"deploy:create"}'

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

# 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:alice@company.com","roleId":"ROLE_ID"}'

Create a Team and Grant Access

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

bash

# 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"}'

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/authorize/workspace/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>

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>

Error Handling

Role Not Found

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.

Permission Denied

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.

Invalid Subject Format

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.

Cannot Delete Built-in Role

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

</troubleshooting>