Project permissions

Project-level permissions apply to all workspaces and Stacks within a specific project.

Background

If you are in an HCP Terraform organization, you can manage user access and permissions through teams. Refer to the following topics for information about setting permissions in HCP Terraform:

Set permissions
Organization permissions reference
Workspace permissions reference
Effective permissions provides information about competing permissions.

Note

In HashiCorp Cloud Platform (HCP) Europe organizations, you manage user access through HCP groups. HCP roles automatically grant permissions in HCP Terraform, and you can add additional fine-grained roles within HCP Terraform itself. To learn more about HCP roles, refer to HCP group roles. To learn more about HCP Europe, refer to Use HCP Terraform in Europe.

Project roles and permissions

A role is a preselected set of permissions that you can assign to a team or group.

The following table shows the permissions granted by each project role. Each role builds upon the previous level, with Admin granting the most comprehensive access.

Permission category	Permission	Admin	Maintain	Write	Read
Project access	Read project	✅	✅	✅	✅
	Update project settings	✅	❌	❌	❌
	Delete project	✅	❌	❌	❌
Workspace management	Create workspaces	✅	✅	❌	❌
	Move workspaces	✅	❌	❌	❌
	Delete workspaces	✅	✅	❌	❌
Group management	Manage team permissions	✅	❌	❌	❌
	Read team assignments	✅	❌	❌	❌
Run Access	Apply runs	✅	✅	✅	❌
	Plan runs	✅	✅	✅	❌
	Read runs	✅	✅	✅	✅
Variable access	Read and write variables	✅	✅	✅	❌
	Read variables	✅	✅	✅	✅
Variable set access	Manage variable sets	✅	❌	❌	❌
	Read variable sets	✅	❌	❌	❌
State access	Read and write state	✅	✅	✅	❌
	Read state	✅	✅	✅	✅
	Read outputs only	✅	✅	✅	✅
Other controls	Download Sentinel mocks	✅	✅	✅	❌
	Lock and unlock workspaces	✅	✅	✅	❌
	Manage workspace run tasks	✅	❌	❌	❌

In an HCP Europe organization, you can grant permissions at the project-level through both HCP and HCP Terraform roles. To learn more about assigning permissions in HCP Europe organizations, refer to HCP group roles.

Project admin

Each project has a group of permissions under the Admin role. This role grants permissions for the project and the workspaces and Stacks that belong to that project.

Members of teams with Admin permissions for a project have general workspace permissions for every workspace, as well as Admin access for every Stack, in the project, and the ability to do the following:

Read and update project settings.
Delete the project.
Move workspaces and Stacks into or out of the project. This also requires project admin permissions for the source or destination project.
Grant or revoke project permissions for visible teams. Project admins cannot view or manage access for teams that are secret, unless those admins are also organization owners.
Admin access for all workspaces and Stacks in this project, including the ability to:
- Create, read, update, and delete workspaces and Stacks in this project.
- Initiate, cancel, or apply runs for workspaces and Stacks in the project.

Project maintain

Assign the Maintain role when users are responsible for managing existing infrastructure in a single project. The role also grants the ability to create new workspaces and Stacks in that project. Maintain access grants full control of everything in the project, including the following permissions:

Read the project name.
Admin access for all workspaces and Stacks in this project, including the ability to:
- Create, read, update, and delete workspaces and Stacks in this project.
- Initiate, cancel, or apply runs for workspaces and Stacks in the project.

Project write

Assign the Write role when users are responsible for most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following permissions:

Read the project name.
Write access for all workspaces and Stacks in this project, including the ability to:
- Read workspaces and Stacks in this project.
- Initiate, cancel, or apply runs for workspaces and Stacks in the project.

Project read

Assign the Read role to users who need to view information about the status and configuration of managed infrastructure but are not responsible for maintaining that infrastructure. Read access grants the permissions to:

Read the project name.
Read access for all workspaces and Stacks in this project.

Custom project role

Custom permissions enable you to assign specific and granular permissions to a team. You can use custom permission sets to create task-focused permission sets and control sensitive information.

Note

Stacks do not support custom group permissions.

You can create a set of custom permissions using any of the permissions listed in the Project roles and permissions table.

Project access

The following table summarizes the available project access permissions. Click on a specific permission name to learn more about that permission level.

Permission name	Description
Read	View information about the project including the name.
Update	Update the project name.
Delete	Delete the project.

Note

In HCP Europe organizations, you cannot assign Project access to a group in HCP Terraform. Instead, assign an HCP role that grants Project access to that group, then HCP Terraform automatically inherits those permissions. To learn more about which HCP roles grant project access, refer to HCP group roles.

Read

Allows users to view information about the project including the name.

Update

Allows users to update the project name. This permission implies permission to read.

Delete

Allows users to delete the project. This permission implies permission to update and read.

Workspace management

The following table summarizes the available workspace management permissions within the project.

Permission name	Description
Create workspaces	Create workspaces in the project.
Move workspaces	Move workspaces into or out of the project.
Delete workspaces	Delete workspaces in the project.

Create workspaces

Allow users to create workspaces in the project. This grants read access to all workspaces in the project.

Move workspaces

Allows users to move workspaces out of the project. A user must have this permission on both the source and destination project to successfully move a workspace from one project to another.

Delete workspaces

Allows users to delete workspaces in the project.

Depending on the organization's settings, workspace admins may only be able to delete the workspace if it is not actively managing infrastructure. Refer to Deleting a Workspace With Resources Under Management for details.

Group management

In HashiCorp Cloud Platform (HCP) Europe organizations, you manage user access through HCP groups, and use group management permissions instead of team management permissions.

The following table summarizes the available group management permissions for the project.

Permission name	Description
None	No access to view groups assigned to the project.
Read	View groups assigned to the project for groups.
Manage	Set or remove project permissions for groups.

None

No access to view groups assigned to the project.

Read

Allows users to see groups assigned to the project for visible groups.

Manage

Allows users to set or remove project permissions for visible groups.

Team management

The following table summarizes the available team management permissions for the project.

Permission name	Description
None	No access to view teams assigned to the project.
Read	View teams assigned to the project for visible teams.
Manage	Set or remove project permissions for visible teams.

None

No access to view teams assigned to the project.

Read

Allows users to see teams assigned to the project for visible teams.

Manage

Allows users to set or remove project permissions for visible teams. Project admins can not view or manage teams with Visibility set to Secret in their team settings unless they are also organization owners. Refer to Team visiblity for more information.

Run access

The following table summarizes the available run access permissions for workspaces within the project.

Permission name	Description
Read	View information about workspace runs within the project.
Plan	Queue Terraform plans in workspaces within the project.
Apply	Approve and apply Terraform plans in workspaces within the project.

Read

Allows users to view information about remote Terraform runs, including the run history, the status of runs, the log output of each stage of a run, and configuration versions associated with a run.

Plan

Allows users to queue Terraform plans in workspaces within the project, including both speculative plans and normal plans. Normal plans must be approved by a user with permission to apply runs. This permission implies permission to read.

Apply

Allows users to approve and apply Terraform plans, causing changes to real infrastructure. This permission implies permission to plan and read.

Variable access

The following table summarizes the available variable access permissions for workspaces within the project. Refer to Manage variables and variable sets for more information about variables.

Permission name	Description
No access	No access to workspace variables within the project.
Read	View workspace variables within the project.
Read and write	Edit workspace variables within the project.

No access

No access is granted to the values of Terraform variables and environment variables for workspaces within the project.

Read

Allows users to view the values of Terraform variables and environment variables for workspaces within the project. Note that variables marked as sensitive are write-only and can't be viewed by any user.

Read and write

Allows users to read and edit the values of variables in workspaces within the project.

Variable set access

The following table summarizes the available permissions for creating and managing sets of variables in the project. Refer to Manage variables and variable sets for more information about variable sets.

Permission name	Description
None	No access to variable sets owned by the project.
Read	View variable sets owned by the project.
Manage	Create, update, and delete variable sets owned by the project.

None

No access to variable sets owned by the project, but users can view variable sets that have been applied to the project and its workspaces if their Variable access permission is set to Read or Read and write .

Read

Allows users to view variable sets owned by this project.

Manage

Allows users to read, create, update, and delete variable sets owned by the project.

State access

The following table summarizes the available state access permissions for workspaces within the project. Refer to State to learn about state in Terraform.

Permission name	Description
No access	No access to workspace state within the project.
Read outputs only	Access public outputs from workspace state within the project.
Read	Read complete state files from workspaces within the project.
Read and write	Create new state versions in workspaces within the project.

No access

No access is granted to the state file from workspaces within the project.

Read outputs only

Allows users to access values in the workspace's most recent Terraform state that have been explicitly marked as public outputs. This permission is required to access the State Version Outputs API endpoint.

Read

Allows users to read complete state files from workspaces within the project. State files are useful for identifying infrastructure changes over time, but often contain sensitive information. This permission implies permission to read outputs only.

Read and write

Allows users to directly create new state versions in workspaces within the project. This permission is required for performing local runs when the workspace's execution mode is set to "local". This permission implies permission to read.

Other controls

The following table summarizes additional control permissions for the project.

Permission name	Description
Download Sentinel mocks	Download data from runs for developing Sentinel policies.
Lock/unlock workspaces	Manually lock workspaces to prevent runs.
Manage workspace Run Tasks	Associate or dissociate run tasks with workspaces.

Download Sentinel mocks

Allows users to download data from runs in workspaces within the project in a format that can be used for developing Sentinel policies. This run data is very detailed, and often contains unredacted sensitive information.

Refer to Generate mock Sentinel data with Terraform for more information about Sentinel mocks.

Lock/unlock workspaces

Allows users to manually lock workspaces within the project to temporarily prevent runs. When a workspace's execution mode is set to Local, enable the Lock/unlock workspaces permission to perform local CLI runs using the workspace's state.

Refer to Workspace settings for information about execution modes and locking workspaces.

Manage workspace Run Tasks

Allows users to associate or dissociate run tasks with workspaces within the project. HCP Terraform creates run tasks at the organization level, where you can manually associate or dissociate them with specific workspaces. Refer to Set up run task integrations for more information about run tasks.

HCP group roles

In an HCP Europe organization, you manage user access through groups. To learn how to set up groups and assign users to them in HCP, refer to Groups. To learn more about HCP Europe, refer to Use HCP Terraform in Europe.

You can assign permissions to HCP groups in two ways:

HCP roles - You can assign HCP roles to groups in the HashiCorp Cloud Platform (HCP), and these roles automatically grant permissions in HCP Terraform.
HCP Terraform roles - Assign additional permissions at the organization, project, and workspace level to further refine group access in HCP Terraform.

Each permission a user is granted is additive. HCP Terraform grants a user the highest permissions possible, regardless of whether that permission was set by an HCP or HCP Terraform role.

The following table lists which project-level permissions each HCP role automatically grants in HCP Terraform:

Permission Category	HCP Terraform permission name	Admin role	Contributor role	Viewer
Project access	Read project	✅	✅	✅
	Update project	✅	❌	❌
	Delete project	✅	❌	❌
Workspace management	Create workspaces	✅	❌	❌
	Move workspaces	✅	❌	❌
	Delete workspaces	✅	❌	❌
Group management	Manage teams	✅	❌	❌
Run access	Apply runs	✅	❌	❌
	Plan runs	✅	❌	❌
	Read runs	✅	❌	✅
Variable access	Read and write variables	✅	❌	❌
	Read variables	✅	❌	✅
Variable set access	Manage variable sets	✅	❌	❌
	Read variable sets	✅	❌	❌
State access	Read and write state	✅	❌	❌
	Read state	✅	❌	✅
Other controls	Download Sentinel mocks	✅	❌	❌
	Lock/unlock workspaces	✅	❌	❌
	Manage workspace run tasks	✅	❌	❌