{"id":79374,"date":"2026-10-15T08:26:58","date_gmt":"2026-10-15T08:26:58","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=79374"},"modified":"2026-10-15T08:30:18","modified_gmt":"2026-10-15T08:30:18","slug":"terraform-cloud-hcp-terraform-organization-project-workspace-team-user-mapping","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/terraform-cloud-hcp-terraform-organization-project-workspace-team-user-mapping\/","title":{"rendered":"Terraform Cloud (HCP Terraform) \u2014 Organization, Project, Workspace, Team & User Mapping"},"content":{"rendered":"\n

Updated: October 15, 2026 | Based on current HashiCorp documentation<\/p>\n\n\n\n

Terraform Cloud is now called HCP Terraform. Its architecture separates infrastructure organization from user access management (RBAC).<\/p>\n\n\n\n

The most important point is that these five components do not form one linear hierarchy.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Teams receive permissions on the organization, projects, and workspaces. Users receive those permissions through team membership. A user may belong to multiple teams, and a team may access multiple projects and workspaces.<\/p>\n\n\n\n

1. Understanding all five components<\/h2>\n\n\n\n
Component<\/th>Purpose<\/th>Relationship<\/th><\/tr>
Organization<\/td>Top-level administrative boundary for Terraform infrastructure, teams, policies and settings<\/td>Contains projects and teams<\/td><\/tr>
Project<\/td>Groups related workspaces and controls access to them<\/td>Belongs to one organization<\/td><\/tr>
Workspace<\/td>Manages Terraform configuration, runs, variables and its own state<\/td>Belongs to exactly one project<\/td><\/tr>
Team<\/td>Groups users and defines their permissions<\/td>Created within an organization; assigned roles at different scopes<\/td><\/tr>
User<\/td>Individual identity accessing HCP Terraform<\/td>Can belong to multiple teams and organizations<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Important cardinality mapping<\/h3>\n\n\n\n
Relationship<\/th>Mapping<\/th><\/tr>
Organization \u2192 Project<\/td>One to many<\/td><\/tr>
Project \u2192 Workspace<\/td>One to many<\/td><\/tr>
Organization \u2192 Team<\/td>One to many<\/td><\/tr>
Team \u2194 User<\/td>Many to many within organization membership<\/td><\/tr>
Team \u2194 Project<\/td>Many to many via permissions<\/td><\/tr>
Team \u2194 Workspace<\/td>Many to many via permissions<\/td><\/tr>
Workspace \u2192 Project<\/td>Exactly one project<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

All workspaces start in a Default Project unless another project is selected. The default project can be renamed but not deleted.<\/p>\n\n\n\n

2. Complete component relationship diagram<\/h2>\n\n\n\n
\nflowchart TB\n    O[\"ORGANIZATION\"]\n    P[\"PROJECTS\"]\n    W[\"WORKSPACES\"]\n    T[\"TEAMS\"]\n    U[\"USERS\"]\n\n    O -->|\"Contains\"| P\n    P -->|\"Contains\"| W\n\n    O -->|\"Contains\"| T\n    T -->|\"Membership\"| U\n\n    T -.->|\"Organization permissions\"| O\n    T -.->|\"Project roles\"| P\n    T -.->|\"Workspace roles\"| W\n\n    classDef org fill:#dbeafe,stroke:#2563eb,color:#1e40af\n    classDef infra fill:#dcfce7,stroke:#16a34a,color:#166534\n    classDef access fill:#fef3c7,stroke:#d97706,color:#92400e\n    class O org\n    class P,W infra\n    class T,U access\n<\/pre><\/div>\n\n\n\n
The solid arrows show membership or resource structure. The dashed arrows represent access grants.<\/p>\n\n\n\n
3. Practical mapping example \u2014 Infrastructure platform<\/h2>\n\n\n\n
Consider one organization managing development, staging and production infrastructure.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/p>\n\n\n\n
<\/p>\n\n\n\n
Illustrative example: projects and workspaces organize infrastructure; teams and users control access.<\/p>\n\n\n\n
Example team-to-resource permission mapping<\/h3>\n\n\n\n
Team<\/th>Target<\/th>Role<\/th>Result<\/th><\/tr>
owners<\/td>Organization<\/td>Owner<\/td>Full organization administration<\/td><\/tr>
devops-engineers<\/td>EVP-NonProd project<\/td>Write<\/td>Plan\/apply all its workspaces<\/td><\/tr>
devops-engineers<\/td>eks-prod workspace<\/td>Plan<\/td>Plan but cannot apply there through this grant<\/td><\/tr>
release-managers<\/td>EVP-Production project<\/td>Write<\/td>Plan\/apply production workspaces<\/td><\/tr>
security-auditors<\/td>Production workspaces<\/td>Custom read-only<\/td>View permitted run details without unnecessarily granting full state access<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
The production Plan<\/code> assignment for DevOps is granted directly on the workspace. The team does not need project-wide Write<\/code> access.<\/p>\n\n\n\n
4. Permission levels \u2014 the critical distinction<\/h2>\n\n\n\n
Project permissions<\/h3>\n\n\n\n
Project roles apply across the project’s workspaces and Stacks.<\/p>\n\n\n\n
Role<\/th>Capabilities<\/th><\/tr>
Admin<\/td>Full project management, including access assignments, workspaces and runs<\/td><\/tr>
Maintain<\/td>Manage workspace lifecycle and operations, including create\/delete and plan\/apply, without full project administration<\/td><\/tr>
Write<\/td>Run Terraform plans and applies, update variables and state<\/td><\/tr>
Read<\/td>View project and workspace information, runs and state<\/td><\/tr>
Custom<\/td>Select individual permissions<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Workspace permissions<\/h3>\n\n\n\n
Role<\/th>Read<\/th>Plan<\/th>Apply<\/th>Manage workspace settings<\/th><\/tr>
Read<\/td>Yes<\/td>No<\/td>No<\/td>No<\/td><\/tr>
Plan<\/td>Yes<\/td>Yes<\/td>No<\/td>No<\/td><\/tr>
Write<\/td>Yes<\/td>Yes<\/td>Yes<\/td>No<\/td><\/tr>
Admin<\/td>Yes<\/td>Yes<\/td>Yes<\/td>Yes<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Custom workspace permissions are also available.<\/p>\n\n\n\n
Notice that Project Write gives write permissions to all workspaces within that project, whereas Workspace Write affects only the selected workspace, unless the team has broader permissions elsewhere.<\/p>\n\n\n\n
How inherited permissions work<\/h3>\n\n\n\n
HCP Terraform permissions are additive, not restrictive overrides.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
If the team has Project Admin, assigning Workspace Read does not reduce its effective access. The same principle applies across organization, project, workspace, and multiple team permissions.<\/p>\n\n\n\n
5. User access and Terraform execution flow<\/h2>\n\n\n\n
This diagram illustrates a user-initiated run. VCS-triggered and automated runs may have different initiation and approval behavior. Authorization does not replace Terraform policy checks, run controls, or cloud-provider IAM permissions.<\/p>\n\n\n\n
\nflowchart TD\n    U[\"User signs into HCP Terraform\"]\n    T[\"Team memberships determine permissions\"]\n    G{\"Authorized for workspace?\"}\n    A[\"Access denied\"]\n    W[\"Workspace\"]\n    R[\"Start or inspect Terraform run\"]\n    PL[\"Terraform Plan\"]\n    AP{\"Apply authorized?\"}\n    STOP[\"Review \/ await approval\"]\n    EX[\"Terraform Apply\"]\n    S[\"Update workspace state\"]\n\n    U --> T --> G\n    G -->|No| A\n    G -->|Yes| W\n    W --> R --> PL --> AP\n    AP -->|No| STOP\n    AP -->|Yes| EX --> S\n<\/pre><\/div>\n\n\n\n
6. How to configure this in the HCP Terraform UI<\/h2>\n\n\n\n
    \n
  1. Create the organization. Sign in at app.terraform.io<\/a> and create your organization. Configure its organization-wide settings.<\/li>\n\n\n\n
  2. Create projects. Open Projects and create logical groupings such as NonProd, Production and Shared Infrastructure.<\/li>\n\n\n\n
  3. Create workspaces. Assign each workspace to its project. Configure VCS or CLI integration, variables, execution mode and cloud credentials.<\/li>\n\n\n\n
  4. Create teams. Navigate to Organization Settings \u2192 Teams. Create teams based on operational responsibilities.<\/li>\n\n\n\n
  5. Invite users. Navigate to Organization Settings \u2192 Users, invite users by email, and associate them with appropriate teams.<\/li>\n\n\n\n
  6. Grant project access. Navigate to Project \u2192 Settings \u2192 Team access. Assign Read, Write, Maintain, Admin or custom permissions.<\/li>\n\n\n\n
  7. Grant workspace exceptions. Navigate to Workspace \u2192 Settings \u2192 Team access when a particular team needs additional permissions on a specific workspace.<\/li>\n\n\n\n
  8. Validate effective permissions. Test with representative users before allowing access to sensitive or production infrastructure.<\/li>\n<\/ol>\n\n\n\n
    These navigation paths follow HashiCorp’s current standard HCP Terraform permission-setting documentation.<\/p>\n\n\n\n
    \"\"\/<\/figure>\n\n\n\n
    HashiCorp Developer<\/p>\n\n\n\n
    7. Recommended best practices<\/h2>\n\n\n\n
    Recommendation<\/th>Reason<\/th><\/tr>
    Use projects as access boundaries<\/td>Keep teams responsible only for relevant infrastructure<\/td><\/tr>
    Separate production and nonproduction permissions<\/td>Avoid broad write access to sensitive workspaces<\/td><\/tr>
    Use workspaces for separate infrastructure states<\/td>Reduce blast radius and improve lifecycle management<\/td><\/tr>
    Assign permissions to teams rather than individuals<\/td>Makes onboarding\/offboarding and auditing easier<\/td><\/tr>
    Restrict the Owners team<\/td>Its members have maximum organization permissions<\/td><\/tr>
    Prefer custom read permissions for auditors<\/td>Default Read roles can allow full Terraform state access<\/td><\/tr>
    Keep cloud IAM separate from HCP Terraform RBAC<\/td>Terraform access does not automatically grant AWS\/Azure permissions<\/td><\/tr>
    Apply consistent workspace naming<\/td>Simplifies searching, automation and maintenance<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Security warning: Workspace Read and Project Read include the ability to read full state files. Terraform state can contain sensitive information, so use custom permissions where only run history or selected outputs should be visible.<\/p>\n\n\n\n
    \"\"\/<\/figure>\n\n\n\n
    HashiCorp Developer<\/p>\n\n\n\n
    8. Important 2026 considerations<\/h2>\n\n\n\n
    HCP Terraform Europe: The newer HCP Europe organizational model uses HCP groups and roles instead of conventional HCP Terraform teams. Standard HCP Terraform organizations continue to use teams.<\/p>\n\n\n\n
    \"\"\/<\/figure>\n\n\n\n
    HashiCorp Developer<\/p>\n\n\n\n
    Stacks: A project can contain Terraform Stacks as well as workspaces, and project-level permissions can extend to both.<\/p>\n\n\n\n
    \"\"\/<\/figure>\n\n\n\n
    HashiCorp Developer<\/p>\n\n\n\n
    Plans and licensing: Projects are broadly available, but team management and project permission-management capabilities depend on the HCP Terraform edition.<\/p>\n\n\n\n
    \"\"\/<\/figure>\n\n\n\n
    HashiCorp Developer<\/p>\n\n\n\n
    +1<\/p>\n\n\n\n
    Final mapping to remember<\/h2>\n\n\n\n
    Question<\/th>Answer<\/th><\/tr>
    Who owns the project?<\/td>Organization<\/td><\/tr>
    Who owns the workspace?<\/td>Project<\/td><\/tr>
    Who owns the team?<\/td>Organization<\/td><\/tr>
    Who belongs to the team?<\/td>Users<\/td><\/tr>
    Who receives permission assignments?<\/td>Teams<\/td><\/tr>
    Where are permissions applied?<\/td>Organization, Project, Workspace<\/td><\/tr>
    Who executes Terraform runs?<\/td>Workspaces, using their configured execution mode<\/td><\/tr>
    Where is Terraform state stored?<\/td>Separately for each HCP Terraform workspace<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    The simplest correct mental model:<\/p>\n\n\n\n
    Organization \u2192 Project \u2192 Workspace defines what infrastructure is managed and where.<\/p>\n\n\n\n
    Organization \u2192 Team \u2192 Users, with team roles on projects and workspaces, defines who can access and change that infrastructure.<\/p>\n\n\n\n
    Official references: Projects<\/a>, Permissions overview<\/a>, and Managing permissions<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Updated: October 15, 2026 | Based on current HashiCorp documentation Terraform Cloud is now called HCP Terraform. Its architecture separates infrastructure organization from user access management (RBAC)…. <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[11138],"tags":[],"class_list":["post-79374","post","type-post","status-publish","format-standard","hentry","category-best-tools"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/79374","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=79374"}],"version-history":[{"count":4,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/79374\/revisions"}],"predecessor-version":[{"id":79382,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/79374\/revisions\/79382"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=79374"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=79374"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=79374"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}