Skip to main content
Welcome back. In this lesson we will cover HCP Terraform teams and permissions so you understand how access is modeled and enforced within the platform. I’ll assume you already know basic concepts of users, teams, and permissions from other platforms. What matters here is how HCP Terraform structures and applies those concepts. Users and organizations A user in HCP Terraform is an individual account tied to an email address — for example, Sarah. A single user can belong to multiple organizations. In other words, Sarah might be a member of a training organization, a development organization, and her own personal organization. Each organization is an isolated environment with its own workspaces, teams, and permissions. What Sarah can do in one organization does not affect what she can do in another. You can think of it like a GitHub account: a single personal account that can be added to different organizations.
The image illustrates the structure of HCP Terraform users, showing an account linked to multiple organizations: Training, Development, and Personal. It uses a purple color scheme and includes an abstract person icon and email.
Teams and scope of access Within an organization, users are grouped into teams. Teams are the primary unit for assigning access because permissions are normally granted to teams rather than to individual users. Consider two common approaches:
  • Granting a team access at the project level so it automatically covers every workspace in that project (including future ones).
  • Granting a team access to specific workspaces for a more granular control, useful for sensitive infrastructure like networking.
Both patterns are valid and often used together depending on organizational needs.
The image is a diagram depicting HCP Terraform teams, showing the Mobile App Team and Network Engineering Team, along with their respective projects and workspaces within an HCP Terraform Organization.
Access model summary
  • Users → belong to teams.
  • Teams → receive permissions.
  • Permissions → determine what actions a team (and therefore its members) can perform.
Granting permissions at the team level simplifies administration and scale.
The image explains the access control hierarchy, featuring three components: "Users," "Teams," and "Permissions," each with a brief description.
Key rules and best practices
  • Permissions are additive. HCP Terraform grants the most permissive effective permission a user has across all their teams. For example, if one team provides read and another provides write to the same workspace, the user receives write access.
  • Apply the principle of least privilege. Only grant teams the permissions they actually need, because permissions stack across multiple team memberships.
  • Every organization has an Owners team with full admin access across the organization (workspaces, projects, policies, VCS settings, private registry, run tasks, etc.). Owners can manage everything and cannot be deleted. Keep Owners membership small and audit it regularly.
The image is a presentation slide titled "The Owners Team," outlining administrative tasks such as managing policies, workspaces, private registries, VCS settings, policy overrides, and run tasks. It indicates that the Owners team has full admin access in an organization.
Team visibility and tokens
  • Team visibility: Teams can be visible (any organization member can see the team and its membership) or secret (only the team members and organization owners can see it). Secret teams are useful for sensitive groups such as security or incident response teams.
  • Team API tokens: Each team can generate API tokens for automation (CI/CD, scripts). A team token inherits the same permissions as the team itself. Historically there was a limit of a single token per team, but HCP Terraform now allows multiple team tokens per team (GA feature).
The image is a presentation slide titled "HCP Terraform Teams," detailing team visibility options (Visible and Secret) and information about team tokens for API operations on workspaces.
Permission levels (scope hierarchy) Permissions in HCP Terraform are defined at three levels:
  • Organization-level: Broad permissions that apply across the organization (e.g., managing workspaces, policies, VCS settings). The Owners team typically holds these privileges, but you can grant specific organization-level permissions to other teams.
  • Project-level: Scoped to a project and all workspaces inside it. Roles can be preset (read, plan, write, admin) or custom. Granting project-level access is an efficient way to manage multiple related workspaces.
  • Workspace-level: The most granular scope. Preset roles include read, plan, write, admin, or you can define custom permissions. To perform an apply action, a user/team needs write permission on that workspace.
Remember: permissions are additive across these levels — the most permissive role wins for any given workspace.
The image outlines the hierarchy of organization, project, and workspace permissions, detailing what each level manages and controls. It includes descriptions of permissions at each level, such as manage, read, write, and custom options.
Practical example Imagine an organization where the Owners create three teams: AppOne, Mobile, and X. Only owners or those with team management permissions can create teams and assign roles.
  • AppOne team:
    • Plan access on production AppOne workspaces (they can queue runs/plans but cannot apply).
    • Write access on dev workspaces (they can plan and apply in dev).
  • Mobile team:
    • Write access on dev mobile workspaces (plan and apply).
    • Plan-only access on mobile production workspaces (need approval to apply).
This is a common pattern: tighter controls in production and more permissive access in development. This illustrates role-based access control (RBAC) in practice — assigning the minimum necessary privileges per team and environment.
The image is a diagram explaining Role-Based Access Control (RBAC) for HCP Terraform, showing the hierarchy and permissions of an organization owner and various teams managing different workspaces.
Exam-focused summary (Terraform Associate) Make sure you understand:
  • The relationship between users, teams, and permissions: users join teams; teams receive permissions.
  • Every organization has an Owners team with full access; it cannot be deleted.
  • The three permission scopes: organization, project, and workspace.
  • Permissions are additive: HCP Terraform grants the highest effective permission a user has across team memberships and scopes.
If you grasp those concepts, you’ll be well prepared for exam questions about teams and permissions. Related topic A related topic is the private registry — how your organization can share reusable Terraform modules and providers internally.

Watch Video