Skip to main content
Welcome — this lesson explains how teams and permissions are modeled and enforced in HCP Terraform. It assumes familiarity with basic identity and access concepts (users, groups/teams, roles) and focuses on how those concepts map to HCP Terraform’s organization, project, and workspace scopes.
This guide covers core concepts you’ll see on the job and in certification exams: users vs. teams, permission scopes, the Owners team, team visibility, and team tokens. Read each section to understand where to assign roles for least-privilege access.

​
Users and organizations

  • A user is an individual account tied to an email address.
  • One user can belong to multiple organizations (for example: personal, training, and work orgs).
  • Organizations are isolated: workspaces, projects, teams, and permissions in one organization do not affect another.
Think of an organization like a GitHub organization: one account can be added to multiple organizations, each with independent repositories and access rules.

​
Teams, Projects, and Workspaces

Teams group users within an organization. Assigning permissions to teams (rather than individual users) simplifies access management and enforces consistent role-based access control. In the diagram below, the Mobile App Team is granted access at the project level (dev-mobile-project), which automatically covers every workspace in that project — including any future workspaces. The Network Engineering Team is granted permissions on individual workspaces (subnet, routes, DNS, firewall), which is useful for cross-project responsibilities or sensitive resources.
An infographic titled "HCP Terraform Teams" showing an HCP Terraform Organization cloud connected to two groups of avatars labeled Mobile App Team and Network Engineering Team. Arrows lead from those teams to purple project/workspace boxes on the right (for example "dev-mobile-project" and several workspaces like subnet, routes, dns, firewall).
Key takeaway: grant permissions at the project level for broad, repeatable access across many workspaces; grant at the workspace level for fine-grained control.

​
Access control hierarchy

At a high level, HCP Terraform structures access using three primary constructs:
  • Users — individual identities that may belong to multiple teams and organizations.
  • Teams — groups of users within a single organization; this is the primary place where permissions are assigned.
  • Permissions — roles assigned to teams at various scopes (organization, project, workspace).
An infographic titled "The Access Control Hierarchy" with three panels labeled Users, Teams, and Permissions, each illustrated (a user avatar, a group holding "TEAM" signs, and a folder with a check). Each panel includes short explanatory text about roles and permission levels.
Important rules to remember:
  • Permissions are additive. If a user belongs to multiple teams, HCP Terraform evaluates the highest effective permission across those teams for a given resource.
  • Follow least privilege: grant teams only the permissions they need. The more teams a user belongs to, the more permissions will accumulate.

​
The Owners team

Every organization includes a built-in Owners team that has full administrative access across the organization (workspaces, projects, policies, VCS settings, private registry, run tasks, and more). Because Owners have unrestricted control, membership should be tightly controlled and audited.
A presentation slide titled "The Owners Team" stating every organization has a default owners team with full admin access. Below it are colorful tiles listing admin actions like Manage Policies, Manage Policy Overrides, Manage Workspaces, Manage Private Registry, Manage VCS Settings, and Manage Run Tasks.
The Owners team is built into the organization and cannot be deleted. Limit membership and enforce SSO or strong authentication for Owners to reduce risk.
Notes:
  • The Owners team cannot be deleted.
  • Authentication for Owners depends on your org’s SSO configuration. If SSO is not enforced, Owners may still be able to sign in with local credentials — review and enforce SSO settings if required.
  • Some trial/free plans limit the ability to create additional teams. Upgrade to a paid plan to enable full team-based access control.

​
Team settings: visibility and tokens

Two important team-level settings:
  • Team visibility
    • Visible team: any organization member can see the team and its membership.
    • Secret team: visible only to members and organization owners. Use secret teams if you must hide membership from the broader organization.
  • Team tokens
    • Teams can create API tokens for automation (CI/CD or scripts). A team token inherits exactly the permissions of the team.
    • HCP Terraform now supports multiple team tokens per team, enabling separate tokens per automation pipeline or integration.

​
Permission levels (scopes)

Permissions are assigned at three scopes. Use the table below to compare scope, typical use cases, and examples of role behavior.
A purple infographic titled "Organization, Project, & Workspace Permissions" showing a three-tier hierarchy — Organizational Level, Project Level, and Workspace Level — with short descriptions of the permissions at each level. A note at the bottom states that permissions are additive and that HCP Terraform grants the highest permission level.
Permissions are additive — HCP Terraform grants the highest effective permission a user has from any team membership or scope.

​
Practical example

Consider this realistic distribution of permissions in an organization that enforces least privilege:
  • AppOne team
    • plan on production workspaces (can create plans but not apply).
    • write on dev workspaces (can plan and apply).
  • Mobile team
    • write on dev workspaces (direct changes allowed in dev).
    • plan on mobile production workspaces (requires approval to apply).
Only users with Owners privileges (or specific team management rights) can create teams and assign permissions. This setup enforces separation of duties: many engineers can validate plans; only approved users can apply changes to production.

​
Exam tips / key points to remember

  • Users belong to teams; teams receive permissions. Avoid granting many direct permissions to individual users.
  • The Owners team exists by default and has full access; it cannot be deleted.
  • Understand three permission scopes: organization, project, and workspace — and when to use each.
  • Permissions are additive: the highest permission from any team or scope applies to the user for a resource.
  • Team tokens inherit the team’s permissions — treat them like credentials and rotate them regularly.
A related topic to study next is the private registry for sharing reusable Terraform modules and providers within your organization.

Watch Video