Teams

Teams are groups of HCP Terraform users within an organization. If a user belongs to at least one team in an organization, they are considered a member of that organization.

The organization can grant workspace permissions to teams that allow its members to start Terraform runs, create workspace variables, read and write state, etc. Teams can only have permissions on workspaces within their organization, although individual users can belong to teams in other organizations.

Hands-on: Try the Manage Permissions in HCP Terraform tutorial.

API and Terraform Enterprise Provider

In addition to the HCP Terraform UI, you can use the following methods to manage teams:

• Teams API to list, create, update, and delete teams
• Team Members API to add and delete users from teams
• Team Tokens API to generate and delete tokens
• Team Access API to manage team access to one or more workspaces
• The tfe provider resources tfe_team, tfe_team_members, and tfe_team_access

The Owners Team

Every organization has a team named owners, and members of the owners team are sometimes called organization owners. An organization's creator is the first member of its owners team, you can add and remove other members in the same way as other teams. In free organizations, the owners team is limited to five members. In paid organizations, the size of the owners team is not limited.

Unlike other teams, you cannot delete the owners team or leave it empty. If there is only one member in an owners team, you must add another user before you can remove the current member.

Refer to Organization Owners for more details about owners team permissions.

Managing Teams

Organization owners can create teams, assign teams permissions, or view the full list of teams. Other users can view any teams marked as visible within the organization, plus any secret teams they are members of. Refer to Team Visibility for details.

Other team management abilities can be granted to members of teams with either one of the manage teams or manage organization access permissions. Refer to Team Permissions for details.

To manage teams:

1. Click Settings and then click Teams. The Team Management page appears, containing a list of all teams within the organization.
2. Click a team to go to its settings page, which lists the team's settings and current members. Members that have two-factor authentication enabled have a 2FA badge.

Creating Teams

To create a new team:

1. Click Settings and then click Teams. The Team Management page appears, containing a list of all teams within the organization.
2. Enter a unique team Name and click Create Team. Team names can include numbers, letters, underscores (_), and hyphens (-).

The new team's settings page appears, where you can add new members and grant permissions.

Deleting Teams

To delete a team:

1. Click Settings then click Teams. The Team Management page appears, containing a list of all teams within the organization.
2. Click the team you want to delete to go to its settings page.
3. Click Delete [team name] at the bottom of the page. The Deleting team "[team name]" box appears.
4. Click Yes, delete team to permanently delete the team and all of its data from HCP Terraform.

Managing Team Membership

Team structure often resembles your company's organizational structure.

Add Users

If the user is not yet in the organization, invite them to join the organization and include a list of teams they should belong to in the invitation. Once the user accepts the invitation, HCP Terraform automatically adds them to those teams.

To add a user that is already in the organization:

1. Click Settings and then click Teams. The Team Management page appears, containing a list of all teams within the organization.
2. Click the team to go to its settings page.
3. Choose a user under Add a New Team Member. Use the text field to filter the list by username or email.
4. Click the user to add them to the team. The user is now listed under Members.

Remove users

To remove a user from a team:

1. Click Settings and then click Teams. The Team Management page appears, containing a list of all teams within the organization.
2. Click the team to go to its settings page.
3. Click the ellipses (...) next to the user's name and select Remove from team. HCP Terraform removes the user from the list of team members.

Team Visibility

Visibility controls who can see a team within the organization. To edit a team's visibility:

1. Click Settings and then click Teams. The Team Management page appears, containing a list of all teams within the organization.
2. Click the team to go to its settings page.
3. Choose a Visibility setting:
   • Visible: Every user in the organization can see the team and its membership. Non-members have read-only access.
   • Secret: Only team members and organization owners can read a team and its membership. This is the default setting.

We recommend making most (or all) teams visible to simplify workspace administration. Secret teams should only have organization-level permissions, since workspace admins cannot manage permissions for teams they cannot view.

API Tokens

Each team can have an API token that is not associated with a specific user. You can manage this API token from the team's settings page under Team API Token . Refer to Team API Tokens for details.

Managing Workspace Access

You can grant teams various permissions on workspaces. Refer to Workspace Permissions for details.

HCP Terraform uses the highest permission level from your teams to determine what actions you can take on a particular resource. For example, if you belong to a team that only has permission to read runs for a workspace and another team with admin access to that workspace, HCP Terraform grants you admin access.

Organization-level permissions and project-level permissions. For example, if a team only has permission to read runs for a given workspace but also has permission to manage workspaces for the organization, members of that team have admin access to the workspace. Conversely, if the team has permission to manage policies for the organization (which gives permission to read runs for all workspaces) and also has admin access to a specific workspace, HCP Terraform grants the higher admin permission level on that workspace.

To manage team permissions on a workspace:

1. Go to the workspace and click Settings > Team Access. The Team Access page appears.
2. Click Add team and permissions to select a team and assign a pre-built or custom permission set.

Managing Project Access

You can grant teams permissions to manage a project and the workspaces that belong to it. Refer to Project Permissions for details.

Managing Organization Access

Organization owners can grant teams permissions to manage policies, projects and workspaces, team and organization membership, VCS settings, private registry providers and modules, and policy overrides across an organization. Refer to Organization Permissions for details.