Permissions overview

To control access within organizations, add users to a team and grant the team permissions to perform actions, such as creating or updating one or more projects or workspaces.

Effective permissions

You can set permissions at the following scopes:

Each permission is additive, granting a user the highest level of permissions possible, regardless of which scope set that permission. A team's effective permissions is the sum of the permissions that team has from every permission level.

The scope that you grant a permission does not matter, the level of access that the permission grants determines what a user can do.

For example, a team has Manage all workspaces permission for an organization, and the Read role in a workspace, then the team has Manage all workspaces permissions for the workspace. HCP Terraform grants Manage all workspaces on that workspace because it is the most permissive level of access.

Conversely, a team's organization permission does not override their workspace permission. For example, the View all workspaces permission set for an organization does not override the Write role set on a specific workspace.

We recommend following the principle of least privilege when configuring permissions. Only grant users the permissions necessary to access the resources they need for their job function.

Permissions managed by external systems

This documentation only refers to permissions that are managed by HCP Terraform and Terraform Enteprise.

The permissions models of systems you integrate with can affect the overall security of your HCP Terraform or Terraform Enterprise organization. Consider the following examples:

When a workspace is connected to a VCS repository, anyone who can merge changes to that repository's main branch can indirectly queue plans in that workspace, regardless of whether they have explicit permission to queue plans or are even a member of your HCP Terraform organization. When auto-apply is enabled, merging changes indirectly start runs.
If you use HCP Terraform's API to create a Slack bot for provisioning infrastructure, anyone who is able to issue commands to that Slack bot can implicitly act with that bot's permissions, regardless of their own membership and permissions in the HCP Terraform organization.
When a run task sends a request to an integrator, it provides an access token that provides access depending on the run task stage:
- For post-plan, it provides access to the run plan JSON and the run task callback.
- All access tokens created for run tasks have a lifetime of 10 minutes

When integrating HCP Terraform with other systems, you are responsible for understanding the effects on your organization's security. An integrated system is able to delegate any level of access that it has been granted, so carefully consider the conditions and events that will cause it to delegate that access.