Workspace permissions

Workspace-level permissions apply to a specific workspace and control what users can do within that workspace.

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
Project 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.

Workspace 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 workspace role. Each role builds upon the previous level, with Admin granting the most comprehensive access.

Permission category	Permission name	Admin	Write	Plan	Read
Run access	Read runs	✅	✅	✅	✅
	Plan runs	✅	✅	✅	❌
	Apply runs	✅	✅	❌	❌
Variable access	Read variables	✅	✅	✅	✅
	Read and write variables	✅	✅	❌	❌
State access	Read outputs only	✅	✅	✅	✅
	Read state	✅	✅	✅	✅
	Read and write state	✅	✅	❌	❌
Other controls	Download Sentinel mocks	✅	✅	❌	❌
	Lock/unlock workspace	✅	✅	❌	❌
	Manage workspace Run Tasks	✅	❌	❌	❌
Admin-only permissions	Read and write workspace settings	✅	❌	❌	❌
	Set workspace permissions for visible teams	✅	❌	❌	❌
	Delete workspace	✅	❌	❌	❌

Workspace admin

Much like the owners team has full control over an organization, each workspace has a special Admin permissions set that grants full control over the workspace. Members of a team with admin permissions on a workspace are sometimes called "workspace admins" for that workspace.

Admin permissions include the highest level of general permissions for the workspace. There are also some permissions that are only available to workspace admins, which generally involve changing the workspace's settings or setting access levels for other teams.

Workspace admins have all other workspace permissions, as well as the ability to do the following:

Read and write workspace settings, such as general settings, notification configurations, and run triggers.
Set or remove workspace permissions for visible teams. Workspace admins cannot view or manage teams with the Secret visibility option enabled unless they are also organization owners.
Delete the workspace
- 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.

Workspace write

The Write permission set is for people who do most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following workspace permissions:

Plan and apply workspace runs.
Read and write the workspace has access to.
Read and write to the state of a workspace.
Lock and unlock the workspace.
Download Sentinel mocks.

Refer to Workspace roles and permissions for details about specific permissions.

Workspace plan

The Plan permission set is for people who might propose changes to managed infrastructure, but whose proposed changes should be approved before they are applied. Plan access grants the following workspace permissions:

Plan workspace runs.
Read variables the workspace has access to.
Read the state of a workspace.

Refer to Workspace roles and permissions for details about specific permissions.

Workspace read

The Read permission set is for people who need to view information about the status and configuration of managed infrastructure in order to do their jobs, but aren't responsible for maintaining that infrastructure. Read access grants the following workspace permissions:

Read workspace runs.
Read variables the workspace has access to.
Read the state of a workspace.

Refer to Workspace roles and permissions for details about specific permissions.

Workspace custom role

Custom permission sets let you assign a custom role with fine-grained permissions. Creating a custom role lets you create a task-focused permission set with a tighter control of sensitive information.

You can use custom permissions to assign any of the permissions listed under workspace roles and permissions, except admin-only permissions.

Run access

The following table summarizes the available run access permissions for the workspace.

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

Read

Allows users to view information about remote Terraform runs. Users can view run history, the status of runs, configuration versions associated with a run, and the log output of each stage of a run. Refer to Run states and stages for more information.

Plan

Allows users to read, queue, and comment on Terraform plans in a workspace. Regular plans require approval from a user with permission to apply runs.

Apply

Allows users to read, plan, approve, and apply Terraform plans. Granting this permission allows team members to change real infrastructure.

Variable access

The following table summarizes the available permissions for accessing workspace variables.

Permission name	Description
No access	No access to workspace variables.
Read	View workspace variables and environment variables.
Read and write	Edit workspace variables and environment variables.

No access

No access is granted to the values of Terraform variables and environment variables for the workspace.

Read

Allows users to view the values of Terraform variables and environment variables for the workspace. 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 the workspace.

State access

The following table summarizes the available state access permissions for the workspace.

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

No access

No access is granted to the state file from the workspace.

Read outputs only

Allows users to access values in the workspace's most recent Terraform state that have been explicitly marked as public outputs. Refer to Define outputs to expose module data to learn more.

Configuration authors often use output values to interface with other workspaces that manage loosely-coupled collections of infrastructure. Making output values readable lets people who have no direct responsibility for the managed infrastructure in one workspace still indirectly use some of its functions in their workspaces.

This permission is required to use the following features:

Call the /state-versions API endpoint
Run the terraform output command
Use the terraform_remote_state data source against the workspace.

Read

Allows users to read complete state files from the workspace. 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 read and directly create new state versions in the workspace. This permission is required for performing local runs when the workspace's execution mode is set to Local.

This permission is also required to use any of the Terraform CLI's state manipulation and maintenance commands against this workspace, including terraform import, terraform taint, and the various terraform state subcommands.

Other controls

The following table summarizes additional control permissions for the workspace.

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

Download Sentinel mocks

Allows users to download data from runs in the workspace in a format that you can use for developing Sentinel policies. This run data from Sentinel mocks is detailed and may contain unredacted sensitive information.

Lock/unlock workspace

Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to Local, you must grant this permission so that team members can perform local CLI runs using the workspace's state.

Manage workspace Run Tasks

Allows users to associate or dissociate run tasks with the workspace. HCP Terraform creates run tasks at the organization level, where you can manually associate or dissociate them with specific workspaces.

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 Terraform in 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 shows which workspace-level permissions each HCP role automatically grants in HCP Terraform:

Permission Category	HCP Terraform workspace permission	Admin	Contributor	Viewer
Run access	Read runs	✅	✅	✅
	Plan runs	✅	✅	❌
	Apply runs	✅	✅	❌
Variable access	Read variables	✅	✅	✅
	Read and write variables	✅	✅	❌
State access	Read outputs only	✅	✅	✅
	Read state	✅	✅	✅
	Read and write state	✅	✅	❌
Other controls	Download Sentinel mocks	✅	✅	❌
	Lock/unlock workspace	✅	✅	❌
	Manage workspace Run Tasks	✅	✅	❌