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 — General platform user. By default, members do not have access to any resources and must be granted access explicitly 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.
Updating permissions for Admin role is not allowed and by default contains all the permissions.

​
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.
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 Gateway Configs.
This allows all the Users access to view all the Gateway Controls by default.
Default Member role comes with following permissions:
  • settings:ListSettings
  • repository:CreateRepository
  • secret-group:CreateSecretGroup
  • user:ListUsers