Grant users, teams, virtual accounts, and agents the access they need in TrueFoundry.
TrueFoundry access control answers one question: who can do what, and where?
A subject is the identity receiving access: a user, team, virtual account, or agent.
A resource is the object being accessed, such as a model provider account, MCP server, agent, cluster, workspace, repository, or secret group.
A role is a named set of allowed actions. For example, the User role can use a model provider account, while the Manager role can also update it.
Assigning a role to a subject for a resource creates a role binding. Access is managed independently from the resource configuration, so you can change who has access without editing or redeploying the resource — from the UI, or as code.
Use the narrowest access that lets someone complete their work:
Access to one resource: grant a resource role from that resource’s Access Control page.
The same tenant-wide capability for several people: create or use a tenant role, assign it to a team, and manage membership in that team.
Let people on a team manage its Virtual Accounts: update the Team Member or Team Manager default role.
A user receives the grants assigned to them and the grants assigned to every team they belong to. TrueFoundry combines these grants, so removing one grant does not remove access provided by another. A virtual account receives only the grants assigned to that account.
Start from Access when you want to understand or update everything assigned to one identity:
Users: open Access > Users. Edit the user for tenant roles, or use Manage Permissions to review resource access.
Teams: open Access > Teams. Edit the team for tenant roles and membership, or use Manage Permissions to review resource access inherited by its members.
Virtual Accounts: open Access > Virtual Accounts, then use Manage Permissions from the three-dot menu.
Agents: select Agents while granting access from a resource’s Access Control page.
When investigating unexpected access for a user, check both their direct grants and the grants on their teams. For a virtual account, check only the grants assigned to that account.
Every grant made from Access Control is stored as a role binding, and you can write one directly as a manifest to keep access in Git and review it like any other change. Apply it with tfy apply or the role bindings API. Re-applying a manifest with the same name updates that binding rather than creating a new one.
ws-staging-editors.yaml
type: role-bindingname: ws-staging-editorssubjects: - type: user name: alice@example.com - type: team name: data-sciencepermissions: - resourceType: workspace resourceFqn: tfy-usea1-devtest:tfy-gateway-staging role: workspace-editor
Field
Meaning
name
Binding id. 3–66 characters: starts with a lowercase letter, contains lowercase letters, digits, or hyphens, and ends with a letter or digit.
subjects[].type
user, team, virtualaccount, or agent.
subjects[].name
The email for a user; otherwise the team, virtual account, or agent name.
permissions[].resourceType
Resource kind, such as workspace, cluster, ml-repo, or provider-account.
permissions[].resourceFqn
Fully qualified name of the resource. Copy it from the resource page.
permissions[].role
A role valid for that resource type, such as workspace-editor or provider-account-manager.
A binding pairs either one subject with many permissions or many subjects with one permission — not many of both. To give several people several roles, write one binding per role.
Every team member gets the Team Member role. People marked as managers also get Team Manager. Both roles apply to Virtual Accounts owned by that team.
Team Member gives members read access to their team’s Virtual Accounts by default.
Team Manager lets managers manage team membership and read the team’s Virtual Accounts by default.
Team role access remains with members and ends when they leave. For Virtual Accounts not owned by the team, or for permissions beyond the team role, grant access from Access > Virtual Accounts > Manage Permissions or from the resource’s Access Control page.Admins can change these defaults under Access > Default Roles. For example, add Manage Virtual Account if team members should retrieve tokens, or add Create Virtual Account if team managers should create Virtual Accounts without becoming tenant admins.
Virtual Account permissions in the Team Member default role
Editing Team Member or Team Manager changes that default for every team. Each person remains limited to the teams they belong to.
Tenant roles apply across the tenant. Use them for platform-wide capabilities such as creating resources, listing all resources of a type, managing users, or changing settings.TrueFoundry provides these account roles:
Tenant Admin: full control across the tenant. This role cannot be edited.
Member: the default role for users. It provides a small baseline and can be edited to change that baseline for all members.
Read-Only Member: read-only access across supported resources. This role cannot be edited.
Team roles and tenant roles serve different purposes: Team Member and Team Manager are scoped to a team, while Member, Tenant Admin, Read-Only Member, and custom roles apply tenant-wide.
To one user: go to Access > Users, edit the user, select the role, and save.
To a group: go to Access > Teams, edit the team, select the role, and save. Every user in the team inherits it. To give a Virtual Account that role, open Access > Virtual Accounts and select Manage Permissions.
A user has one tenant role assigned directly. If they also belong to a team that has a tenant role, their effective permissions are the combination of both. Assigning tenant roles to teams is easier to maintain for groups of users.For SCIM-managed organizations, you can assign a role to a team synchronized from your identity provider. See Provision teams via SCIM.
Create a custom role when the default tenant roles are too broad or too narrow. A custom role contains tenant-wide permissions and can be assigned to users or teams.
1
Open Custom Roles
Go to Access > Custom Roles and select Create Role.
2
Define the role
Enter a unique name, display name, and clear description. Then select only the permissions needed for the job.
Permissions grouped by resource type
3
Assign the role
Assign the role to a user from Access > Users, or to a team from Access > Teams.
Custom-role permissions apply across all resources of the selected type. To grant access to only one resource, use that resource’s Access Control page instead.
The catalog below lists every permission that exists in the TrueFoundry platform. These are the building blocks you compose into a custom tenant-level role.
How do I let Team Managers create or manage their team's Virtual Accounts?
Go to Access > Default Roles, edit Team Manager, and select the actions they need:
Read Virtual Account lets managers see Virtual Accounts owned by their team. This is included by default.
Create Virtual Account lets managers create Virtual Accounts for their team.
Manage Virtual Account lets managers update those accounts and retrieve their tokens.
Delete Virtual Account lets managers delete them.
To prevent Team Managers from creating Virtual Accounts, leave Create Virtual Account unselected or remove it if it was previously added.These changes apply to Team Managers in every team, but each manager can act only on resources scoped to their own team.
How do I let Team Members retrieve Virtual Account tokens?
The Team Member role includes Read Virtual Account by default, which lets members see Virtual Accounts owned by their teams. Retrieving a token requires Manage Virtual Account.Go to Access > Default Roles, edit Team Member, add Manage Virtual Account, and save. This change applies to members of every team, but each member can access only Virtual Accounts owned by a team they belong to.Make sure the Virtual Account’s Owned By field identifies the correct team. See Manage Virtual Accounts for token operations.
How do I give an auditor read-only access?
Assign Read-Only Member to the auditor from Access > Users. For a group of auditors, assign it to a team instead.This role provides read-only access across supported resource types and cannot be edited. If the auditor should see only selected resources, grant the viewer or access role on each resource instead.
How do I give someone read-only access to all resources?
Assign Read-Only Member. It is the built-in tenant-wide read-only role. If they should see only certain resources, grant the viewer or access role on those resources instead of using a tenant-wide role.
How do I let certain users create MCP servers without making them Tenant Admin?
Create a custom role with Create MCP Server, then assign that role to the users or to a team they belong to.
1
Create the role
Go to Access > Custom Roles and select Create Role.
2
Add Create MCP Server
Add Create MCP Server and save.
3
Assign the role
Assign it from Access > Users or Access > Teams.
Create MCP Server lets someone create a new MCP server. It does not grant access to existing MCP servers. After creating one, the owner can grant themselves MCP Server Manager from that server’s Access Control page.
How do I let everyone view Gateway Controls without making them Tenant Admin?
Go to Access > Default Roles, edit Member, add List Gateway Controls, and save.
This change applies to every user who has the Member role.
What does the Member role include by default?
Member includes:
cluster:ReadCluster
environment:ListEnvironments
settings:ListSettings
user:ListUsers
repository:CreateRepository
secret-group:CreateSecretGroup
agent:CreateAgent
It does not include access to individual models, MCP servers, workspaces, or other resources. Grant those from each resource’s Access Control page, or through team membership.
What does the Team Member role include by default?
Team Member includes virtual-account:ReadVirtualAccount, scoped to Virtual Accounts owned by the teams the user belongs to. Retrieving a token additionally requires virtual-account:ManageVirtualAccount.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.
