Add a note about additive/effective permissions

[jbonhag]

What

• https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions

Added a note about how the HCP Terraform permission model is additive, so that a user's effective permissions is the sum of their permissions up and down the organization hierarchy.

Why

We call out this behavior in the HCP Terraform UI itself (and link to this permissions page), but it may not be clear how/why this is the case. This note is intended to help make the HCP Terraform permission model a bit more understandable.

---

Merge Checklist

If items do not apply to your changes, add (N/A) and mark them as complete.

Pull Request

• One or more labels describe the type of change (e.g. clarification) and associated product (e.g. HCP Terraform ).
• (N/A) Description links to related pull requests or issues, if any.

Content

• (N/A) Redirects have been added to website/redirects.js for moved, renamed, or deleted pages.
• (N/A) API documentation and the API Changelog have been updated.
• (N/A) Links to related content where appropriate (e.g., API endpoints, permissions, etc.).
• (N/A) Pages with related content are updated and link to this content when appropriate.
• (N/A) Sidebar navigation files have been updated for added, deleted, reordered, or renamed pages.
• (N/A) New pages have metadata (page name and description) at the top.
• (N/A) New images are 2048 px wide. They have HashiCorp standard annotation color (#F92672) and format (rectangle with rounded corners), blurred sensitive details (e.g. credentials, usernames, user icons), and descriptive alt text in the markdown for accessibility.
• (N/A) New code blocks have the correct syntax and line breaks to eliminate horizontal scroll bars.
• (N/A) UI elements (button names, page names, etc.) are bolded.
• The Vercel website preview successfully deployed.

Reviews

• I or someone else reviewed the content for technical accuracy.
• I or someone else reviewed the content for typos, punctuation, spelling, and grammar.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
terraform-docs-common	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 14, 2025 6:53pm

[mkam]

Suggested change

The permissions model is split into organization-level, project-level, and workspace-level permissions. These permissions are additive, meaning that a user on a team is allowed to perform the most permissive action that has been granted on a resource, regardless of the level at which it was granted. For example, if a team has a workspace "read" permission at the organization-level, and they have admin access on a single workspace, users on that team can still apply runs -- the organization-level permission doesn't take precedence over the workspace permissions. When configuring permissions at a particular level, it's important to remember that that team may have permissions above or below the hierarchy that grant a higher level of permission than what's currently being configured. A team's _effective permissions_ are the sum of the permissions that have been granted to them across the entire organization hierarchy.

The permissions model is split into organization-level, project-level, and workspace-level permissions. These permissions are additive, meaning that a user on a team is allowed to perform the most permissive action that has been granted on a resource, regardless of the level at which it was granted. For example, if a team has a workspace "read" permission at the organization-level, and they have admin access on a single workspace, users on that team can still apply runs on that workspace -- the organization-level permission doesn't take precedence over the workspace permissions. When configuring permissions at a particular level, it's important to remember that that team may have permissions above or below the hierarchy that grant a higher level of permission than what's currently being configured. A team's _effective permissions_ are the sum of the permissions that have been granted to them across the entire organization hierarchy.

Also, was thinking this could be two paragraphs because it's looking kind of dense in the preview:
https://terraform-docs-common-git-jbonhag-additive-per-062ddc-hashicorp.vercel.app/terraform/cloud-docs/users-teams-organizations/permissions

[rkoron007]

I love this suggestion! I hope you don't mind that I expanded on this a bit, I tried reworking it for flow and I came up with:

Suggested change

	The permissions model is split into organization-level, project-level, and workspace-level permissions. These permissions are additive, meaning that a user on a team is allowed to perform the most permissive action that has been granted on a resource, regardless of the level at which it was granted. For example, if a team has a workspace "read" permission at the organization-level, and they have admin access on a single workspace, users on that team can still apply runs -- the organization-level permission doesn't take precedence over the workspace permissions. When configuring permissions at a particular level, it's important to remember that that team may have permissions above or below the hierarchy that grant a higher level of permission than what's currently being configured. A team's _effective permissions_ are the sum of the permissions that have been granted to them across the entire organization hierarchy.
	The HCP Terraform permissions model is split into three levels, you can set organization-level, project-level, and workspace-level permissions. Each permission level is additive, granting a user the highest level of permissions possible, regardless of which level set that permission.
	A team's _effective permissions_ is the sum of the permissions granted to that team from all permission levels. For example, if a team has the **View all workspaces** permission at the organization-level and **Admin** permission on a specific workspace, then users on that team have the effective permission of **Admin** on that workspace. An organization-level permission does not take precedence over a workspace-level permission.
	We recommend following the principle of least privilege when configuring permissions, only giving teams access to the resources they need for their job function. When configuring permissions at a particular level, remember that a team may have permissions above or below in the hierarchy that grant a higher level of permission than what you are currently configuring.

Let me know what you think and feel free to push back if anything doesn't feel good about it!

[rkoron007]

Left suggestions for style! Love the idea of adding this ✨

[rkoron007]

I love this suggestion! I hope you don't mind that I expanded on this a bit, I tried reworking it for flow and I came up with:

Suggested change

	The permissions model is split into organization-level, project-level, and workspace-level permissions. These permissions are additive, meaning that a user on a team is allowed to perform the most permissive action that has been granted on a resource, regardless of the level at which it was granted. For example, if a team has a workspace "read" permission at the organization-level, and they have admin access on a single workspace, users on that team can still apply runs -- the organization-level permission doesn't take precedence over the workspace permissions. When configuring permissions at a particular level, it's important to remember that that team may have permissions above or below the hierarchy that grant a higher level of permission than what's currently being configured. A team's _effective permissions_ are the sum of the permissions that have been granted to them across the entire organization hierarchy.
	The HCP Terraform permissions model is split into three levels, you can set organization-level, project-level, and workspace-level permissions. Each permission level is additive, granting a user the highest level of permissions possible, regardless of which level set that permission.
	A team's _effective permissions_ is the sum of the permissions granted to that team from all permission levels. For example, if a team has the **View all workspaces** permission at the organization-level and **Admin** permission on a specific workspace, then users on that team have the effective permission of **Admin** on that workspace. An organization-level permission does not take precedence over a workspace-level permission.
	We recommend following the principle of least privilege when configuring permissions, only giving teams access to the resources they need for their job function. When configuring permissions at a particular level, remember that a team may have permissions above or below in the hierarchy that grant a higher level of permission than what you are currently configuring.

Let me know what you think and feel free to push back if anything doesn't feel good about it!

[rkoron007]

Can we remove this sentence because

Suggested change

	Additionally, every organization has a special team named "owners", whose members have maximal permissions within the organization.
	Every organization also has a special team called the **Owners** team, whose members have the maximum available permissions within the organization.