Skip to main content
TrueFoundry access control works at two levels:
  1. Resource-level roles — assigned directly on a specific resource (cluster, workspace, model, MCP server, etc.) as collaborators. These roles control what a user, team, or virtual account can do on that particular resource.
  2. Tenant-level roles — assigned globally to a user or team within the tenant. These roles define what actions the identity can perform across all resources of that type in the tenant.

​
Resource-level roles (collaborators)

When you add a user, team, or virtual account as a collaborator on a resource, you pick a role that scopes their access to that resource only. Common resource-level roles include: You assign these roles directly on the resource through the Collaborators section when editing a resource. No custom role creation is needed.

​
Tenant-level roles

Tenant-level roles apply across the entire tenant and are configured under Access > Roles. They control tenant-wide actions such as creating new resources, managing users, configuring settings, or listing all resources of a type. Tenant-level roles can be assigned to users or teams. When assigned to a team, every member of that team inherits the role’s permissions.
Custom role creation form showing all tenant-level permissions grouped by resource type

Permissions available when creating a custom tenant-level role

​
Assign a role to a user

Every user in the tenant has exactly one tenant-level role. By default, TrueFoundry ships with two roles:
  • Admin — Full control over the tenant, including users, teams, clusters, workspaces, models, MCP servers, and all other resources. Usually only a few admins per organization.
  • Member — Every user on the platform has this role by default. It grants a small baseline: reading clusters, listing environments, settings and users, and creating repositories, secret groups and agents. See the permissions it grants. Access to individual workspaces, models, MCP servers and other resources is not included and must be granted through resource collaborators or team membership.
You can also create custom roles when the default roles are too broad or too narrow.

​
Assign a role from the UI

Navigate to Access > Users, select a user, and pick the role from the Edit User dialog.

​
Assign a role through team membership

If a user is also a member of a team that has a tenant-level role assigned, the user’s effective permissions are the union of their direct role and every role inherited from their teams. This is the recommended way to manage roles for groups of users — assign the role once on the team and add or remove members as needed. For SCIM-managed organizations, IdP groups synced as TrueFoundry teams can be granted tenant-level roles directly inside TrueFoundry. See Provision teams via SCIM.
If a user’s role is updated manually (for example, promoted to Admin), the manual assignment takes precedence and is preserved even if their team memberships change.

​
Available platform permissions

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.

​
AI Gateway

​
AI Engineering

​
Common

​
Managing Default Roles

TrueFoundry allows customizing default roles for giving flexibility to Admins to decide. For example, we can update the Default team manager role to allow them manage their virtual accounts on their own. Every tenant ships with the following default roles, which you can review and edit under Access > Roles > Default Roles: Team Manager and Team Member are always scoped to the user’s own team, so editing them is the recommended way to delegate Virtual Account access to a team without granting tenant-wide permissions or making anyone an Admin.

​
Managing Custom Roles

Custom roles let you define a specific set of tenant-level permissions and assign them to users or teams. This is useful when the default Admin and Member roles are too broad or too narrow for a particular group.
1

Create new Custom Role

Navigate to Access > Roles > Custom Roles. Click on Create Role.
2

Fill the form

​
string
required
A unique name to identify this role. Should follow the format as Alphanumeric characters and hyphens.
​
string
required
A user-friendly readable display name for this Role.
​
string
required
A breif description about this role and its permissions.
​
array
required
Permissions for the role. Refer to Available platform permissions to understand these permissions.
  • Permissions are applied to all the resources in the tenant.
  • Provider Account should be used to give permissions for Models, Guardrails, and Integrations.
3

Assign the role to a user or team

Assign to a user: Navigate to Access > Users. Select the user, click Edit User, select the role, and save.
Assign to a team: Navigate to Access > Teams. Select the team, click Edit Team, select the role, and save. Every member of the team inherits the permissions from that role.
A user can be assigned only one tenant-level role directly. If the user is also a member of a team with a role, the effective permissions are the union of both.

​
FAQ

You can achieve this by updating the default role for Team Manager to allow them to create or manage their Virtual Account.
1

Edit default Team Manager Role

Navigate to Access > Roles > Default Roles and click on Edit button for the default Team Manager role.
2

Update Team Manager role

Update the permissions based on your requirements.
  • Read Virtual Account: If you want to allow Team Managers view Virtual Accounts owned by their teams.
  • Create Virtual Account: If you want to allow Team Managers create new Virtual Accounts owned by their teams.
  • Manage Virtual Account: If you want to allow Team Managers update Virtual Accounts owned by their teams. This also includes permission to get the token.
  • Delete Virtual Account: If you want to allow Team Managers delete Virtual Accounts owned by their teams.
These permissions apply to all the Team Managers in the Account irrespective of their Teams.
3

Manage Virtual Accounts

Team Managers should now be able to view, create, manage or delete Virtual Account owned by their Team based on the permissions given.
Every member of a team automatically gets the default Team Member role, scoped to the Virtual Accounts owned by that team. Editing this role is the recommended way to let team members work with their team’s Virtual Accounts — they do not need to be made Admins, and they do not need Team Manager access.By default the role comes with Read Virtual Account, so members can view (but not modify) the Virtual Accounts owned by their teams. To let them retrieve the token, add Manage Virtual Account.
1

Edit default Team Member Role

Navigate to Access > Roles > Default Roles and click on Edit button for the default Team Member role.
2

Update Team Member role

Update the permissions based on your requirements.
  • Read Virtual Account: If you want to allow Team Members view Virtual Accounts owned by their teams. This is enabled by default.
  • Manage Virtual Account: If you want to allow Team Members update Virtual Accounts owned by their teams. This also includes permission to get the token, and is the permission to enable if members need to retrieve their team’s Virtual Account tokens themselves.
  • Create Virtual Account: If you want to allow Team Members create new Virtual Accounts owned by their teams.
  • Delete Virtual Account: If you want to allow Team Members delete Virtual Accounts owned by their teams.
Edit Role drawer for the default Team Member role showing Team and Virtual Account permissions with Read Virtual Account selected
These permissions apply to all the Team Members in the Account irrespective of their Teams. Each member can still only act on the Virtual Accounts owned by the teams they belong to.
3

View or retrieve Virtual Account tokens

Team Members should now be able to view the Virtual Accounts owned by their Team, along with any other action you enabled. If you granted Manage Virtual Account, members can retrieve the token using the Get Token button on the Virtual Account. See Manage Virtual Accounts for details.
A Virtual Account is only visible to a team’s members if it is owned by that team. Set the owning team using the Owned By field on the Virtual Account.
Default Team Member role comes with following permissions:
  • virtual-account:ReadVirtualAccount
This is scoped to the Virtual Accounts owned by the teams a user belongs to. Retrieving a Virtual Account token additionally requires virtual-account:ManageVirtualAccount.
You can achieve this by assigning a custom role to those Users to allow them to create or manage their Virtual MCP Servers.
1

Create a new Custom Role

Navigate to Access > Roles > Custom Roles and click on Create Role button.
2

Fill the form

Fill the form with required details and add Create MCP Server permission to allow just create a new MCP/Virtual MCP Server.
This only allows the Users to create a new MCP Server. They cannot view or update any existing MCP Server in the Account through this permission. User can add themself as MCP Server Manager using collaborator to update and access the MCP Server while creating it first time.
3

Assing the Role to User

Navigate to Access > Users and click Edit for users to allow creating MCP Servers. Assign the created Role.
You can achieve this by editing the default Member role to allow them to view Gateway Controls.
1

Edit default Team Manager Role

Navigate to Access > Roles > Default Roles and click on Edit button on Member role.
2

Update Team Manager role

Update the permissions to add List Gateway Controls and click Update to allow all the Users in the Account view all the AI Gateway Configs.
This allows all the Users access to view all the AI Gateway Controls by default.
Default Member role comes with following permissions:
  • cluster:ReadCluster
  • environment:ListEnvironments
  • settings:ListSettings
  • user:ListUsers
  • repository:CreateRepository
  • secret-group:CreateSecretGroup
  • agent:CreateAgent