terraform page title API Tokens HCP Terraform API Tokens Learn about the level of access granted by user team and organization API This topic describes the distinct types of API tokens you can use to authenticate with HCP Terraform tokens

Answer:
---
page_title: API Tokens - HCP Terraform
description: >-
  Learn about the level of access granted by user, team, and organization API
  tokens.
---

# API Tokens

This topic describes the distinct types of API tokens you can use to authenticate with HCP Terraform.

Note that HCP Terraform only displays API tokens once when you initially create them and are obfuscated thereafter. If the token is lost, it must be regenerated.

Refer to [Team Token API](/terraform/cloud-docs/api-docs/team-tokens) and [Organization Token API](/terraform/cloud-docs/api-docs/organization-tokens) for additional information about using the APIs.

## User API Tokens

API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#api-tokens) documentation.

## Team API Tokens

API tokens may belong to a specific team. Team API tokens allow access to the workspaces that the team has access to, without being tied to any specific user.

Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens.

Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid.

Owners and users with [manage teams](/terraform/cloud-docs/users-teams-organizations/permissions#manage-teams) permissions have the ability to enable and disable team token management for a team, which limits the actions that team members can take on a team token. Refer to [Allow Member Token Management](/terraform/cloud-docs/users-teams-organizations/permissions#allow-member-token-management) for more information.

Team API tokens are designed for performing API operations on workspaces. They have the same access level to the workspaces the team has access to. For example, if a team has permission to apply runs on a workspace, the team's token can create runs and configuration versions for that workspace via the API. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Note that the individual members of a team can usually perform actions the team itself cannot, since users can belong to multiple teams, can belong to multiple organizations, and can authenticate with Terraform's `atlas` backend for running Terraform locally.

If an API token is generated for the "owners" team, then that API token will have all of the same permissions that an organization owner would.

## Organization API Tokens

API tokens may be generated for a specific organization. Organization API tokens allow access to the organization-level settings and resources, without being tied to any specific team or user.

To manage the API token for an organization, go to **Organization settings > API Token** and use the controls under the "Organization Tokens" header.

Each organization can have **one** valid API token at a time. Only [organization owners](/terraform/cloud-docs/users-teams-organizations/teams#the-owners-team) can generate or revoke an organization's token.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Organization API tokens are designed for creating and configuring workspaces and teams. We don't recommend using them as an all-purpose interface to HCP Terraform; their purpose is to do some initial setup before delegating a workspace to a team. For more routine interactions with workspaces, use [team API tokens](#team-api-tokens).

Organization API tokens have permissions across the entire organization. They can perform all CRUD operations on most resources, but have some limitations; most importantly, they cannot start runs or create configuration versions. Any API endpoints that can't be used with an organization API token include a note like the following:

-> **Note:** This endpoint cannot be accessed with [organization tokens](#organization-api-tokens). You must access it with a [user token](/terraform/cloud-docs/users-teams-organizations/users#api-tokens) or [team token](#team-api-tokens).

<!-- BEGIN: TFC:only -->

## Audit trail tokens

You can generate an audit trails token to read an organization's [audit trails](/terraform/cloud-docs/api-docs/audit-trails). Use this token type to authenticate integrations pulling audit trail data, for example, using the [HCP Terraform for Splunk](/terraform/cloud-docs/integrations/splunk) app.

To manage an organization's audit trails token, go to **Organization settings > API Token** and use the settings under the "Audit Token" header.

Each organization can only have a _single_ valid audit trails token. Only [organization owners](/terraform/cloud-docs/users-teams-organizations/teams#the-owners-team) can generate or revoke an organization's audit trails token.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

<!-- END: TFC:only -->

## Agent API Tokens

[Agent pools](/terraform/cloud-docs/agents) have their own set of API tokens which allow agents to communicate with HCP Terraform, scoped to an organization. These tokens are not valid for direct usage in the HCP Terraform API and are only used by agents.

## Access Levels

The following chart illustrates the various access levels for the supported API token types. Some permissions are implicit based on the token type, others are dependent on the permissions of the associated user, team, or organization.

🔵 = Implicit for token type 🔶 = Requires explicit permission

|                                    | User tokens | Team tokens | Organization tokens |
| ---------------------------------- | :---------: | :---------: | :-----------------: |
| **Users**                          |             |             |                     |
| Manage account settings            |      🔵     |             |                     |
| Manage user tokens                 |      🔵     |             |                     |
| **Workspaces**                     |             |             |                     |
| Read workspace variables           |      🔶     |      🔶     |          🔵         |
| Write workspace variables          |      🔶     |      🔶     |          🔵         |
| Plan, apply, upload states         |      🔶     |      🔶     |                     |
| Force cancel runs                  |      🔶     |      🔶     |                     |
| Create configuration versions      |      🔶     |      🔶     |                     |
| Create or modify workspaces        |      🔶     |      🔶     |          🔵         |
| Remote operations                  |      🔶     |      🔶     |                     |
| Manage run triggers                |      🔶     |      🔶     |          🔵         |
| Manage notification configurations |      🔶     |      🔶     |                     |
| Manage run tasks                   |      🔶     |      🔶     |          🔵          |
| **Teams**                          |             |             |                     |
| Create teams                       |      🔶     |      🔶     |          🔵         |
| Modify team                        |      🔶     |      🔶     |          🔵         |
| Read team                          |      🔶     |      🔶     |          🔵         |
| Manage team tokens                 |      🔶     |      🔶     |          🔵         |
| Manage team workspace access       |      🔶     |      🔶     |          🔵         |
| Manage team membership             |      🔶     |      🔶     |          🔵         |
| **Organizations**                  |             |             |                     |
| Create organizations               |      🔵     |             |                     |
| Modify organizations               |      🔶     |             |                     |
| Manage organization tokens         |      🔶     |             |                     |
| View audit trails                  |             |             |          🔵         |
| Invite users to organization       |      🔶     |      🔶     |          🔵         |
| **Sentinel**                       |             |             |                     |
| Manage Sentinel policies           |      🔶     |      🔶     |          🔵         |
| Manage policy sets                 |      🔶     |      🔶     |          🔵         |
| Override policy checks             |      🔶     |      🔶     |                     |
| **Integrations**                   |             |             |                     |
| Manage VCS connections             |      🔶     |      🔶     |          🔵         |
| Manage SSH keys                    |      🔶     |      🔶     |                     |
| Manage run tasks                   |      🔶     |      🔶     |          🔵          |
| **Modules**                        |             |             |                     |
| Manage Terraform modules           |      🔶     | 🔵 (owners) |                     |

## Token Expiration

You can create user, team, and organization tokens with an expiration date and time. Once the expiration time has passed, the token is longer treated as valid and may not be used to authenticate to any API. Any API requests made with an expired token will fail.

HashiCorp recommends setting an expiration on all new authentication tokens. Creating tokens with an expiration date helps reduce the risk of accidentally leaking valid tokens or forgetting to delete tokens meant for a delegated use once their intended purpose is complete.

You can not modify the expiration of a token once you have created it. The HCP Terraform UI displays tokens relative to the current user's timezone, but all tokens are passed and displayed in UTC in ISO 8601 format through the HCP Terraform API.

page title  API Tokens   HCP Terraform description       Learn about the level of access granted by user  team  and organization API   tokens         API Tokens  This topic describes the distinct types of API tokens you can use to authenticate with HCP Terraform   Note that HCP Terraform only displays API tokens once when you initially create them and are obfuscated thereafter  If the token is lost  it must be regenerated   Refer to  Team Token API   terraform cloud docs api docs team tokens  and  Organization Token API   terraform cloud docs api docs organization tokens  for additional information about using the APIs      User API Tokens  API tokens may belong directly to a user  User tokens are the most flexible token type because they inherit permissions from the user they are associated with  For more information on user tokens and how to generate them  see the  Users   terraform cloud docs users teams organizations users api tokens  documentation      Team API Tokens  API tokens may belong to a specific team  Team API tokens allow access to the workspaces that the team has access to  without being tied to any specific user   Navigate to the   Organization settings   API Tokens   Team Token   tab to manage API tokens for a team or create new team tokens   Each team can have   one   valid API token at a time  When a token is regenerated  the previous token immediately becomes invalid   Owners and users with  manage teams   terraform cloud docs users teams organizations permissions manage teams  permissions have the ability to enable and disable team token management for a team  which limits the actions that team members can take on a team token  Refer to  Allow Member Token Management   terraform cloud docs users teams organizations permissions allow member token management  for more information   Team API tokens are designed for performing API operations on workspaces  They have the same access level to the workspaces the team has access to  For example  if a team has permission to apply runs on a workspace  the team s token can create runs and configuration versions for that workspace via the API    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers  Note that the individual members of a team can usually perform actions the team itself cannot  since users can belong to multiple teams  can belong to multiple organizations  and can authenticate with Terraform s  atlas  backend for running Terraform locally   If an API token is generated for the  owners  team  then that API token will have all of the same permissions that an organization owner would      Organization API Tokens  API tokens may be generated for a specific organization  Organization API tokens allow access to the organization level settings and resources  without being tied to any specific team or user   To manage the API token for an organization  go to   Organization settings   API Token   and use the controls under the  Organization Tokens  header   Each organization can have   one   valid API token at a time  Only  organization owners   terraform cloud docs users teams organizations teams the owners team  can generate or revoke an organization s token    permissions citation    intentionally unused   keep for maintainers  Organization API tokens are designed for creating and configuring workspaces and teams  We don t recommend using them as an all purpose interface to HCP Terraform  their purpose is to do some initial setup before delegating a workspace to a team  For more routine interactions with workspaces  use  team API tokens   team api tokens    Organization API tokens have permissions across the entire organization  They can perform all CRUD operations on most resources  but have some limitations  most importantly  they cannot start runs or create configuration versions  Any API endpoints that can t be used with an organization API token include a note like the following        Note    This endpoint cannot be accessed with  organization tokens   organization api tokens   You must access it with a  user token   terraform cloud docs users teams organizations users api tokens  or  team token   team api tokens         BEGIN  TFC only         Audit trail tokens  You can generate an audit trails token to read an organization s  audit trails   terraform cloud docs api docs audit trails   Use this token type to authenticate integrations pulling audit trail data  for example  using the  HCP Terraform for Splunk   terraform cloud docs integrations splunk  app   To manage an organization s audit trails token  go to   Organization settings   API Token   and use the settings under the  Audit Token  header   Each organization can only have a  single  valid audit trails token  Only  organization owners   terraform cloud docs users teams organizations teams the owners team  can generate or revoke an organization s audit trails token    permissions citation    intentionally unused   keep for maintainers       END  TFC only         Agent API Tokens   Agent pools   terraform cloud docs agents  have their own set of API tokens which allow agents to communicate with HCP Terraform  scoped to an organization  These tokens are not valid for direct usage in the HCP Terraform API and are only used by agents      Access Levels  The following chart illustrates the various access levels for the supported API token types  Some permissions are implicit based on the token type  others are dependent on the permissions of the associated user  team  or organization       Implicit for token type     Requires explicit permission                                         User tokens   Team tokens   Organization tokens                                                                                Users                                                                                Manage account settings                                                                 Manage user tokens                                                                        Workspaces                                                                             Read workspace variables                                                              Write workspace variables                                                             Plan  apply  upload states                                                             Force cancel runs                                                                      Create configuration versions                                                          Create or modify workspaces                                                           Remote operations                                                                      Manage run triggers                                                                   Manage notification configurations                                                     Manage run tasks                                                                         Teams                                                                                Create teams                                                                          Modify team                                                                           Read team                                                                             Manage team tokens                                                                    Manage team workspace access                                                          Manage team membership                                                                  Organizations                                                                          Create organizations                                                                    Modify organizations                                                                    Manage organization tokens                                                              View audit trails                                                                       Invite users to organization                                                            Sentinel                                                                               Manage Sentinel policies                                                              Manage policy sets                                                                    Override policy checks                                                                   Integrations                                                                           Manage VCS connections                                                                Manage SSH keys                                                                        Manage run tasks                                                                         Modules                                                                                Manage Terraform modules                             owners                              Token Expiration  You can create user  team  and organization tokens with an expiration date and time  Once the expiration time has passed  the token is longer treated as valid and may not be used to authenticate to any API  Any API requests made with an expired token will fail   HashiCorp recommends setting an expiration on all new authentication tokens  Creating tokens with an expiration date helps reduce the risk of accidentally leaking valid tokens or forgetting to delete tokens meant for a delegated use once their intended purpose is complete   You can not modify the expiration of a token once you have created it  The HCP Terraform UI displays tokens relative to the current user s timezone  but all tokens are passed and displayed in UTC in ISO 8601 format through the HCP Terraform API


terraform tokens and more invite terraform cloud docs users teams organizations organizations users organizations terraform cloud docs users teams organizations organizations page title Users HCP Terraform teams terraform cloud docs users teams organizations teams Create an account edit settings set up two factor authentication create API

Answer:
---
page_title: Users - HCP Terraform
description: >-
  Create an account, edit settings, set up two-factor authentication, create API
  tokens, and more.
---

[organizations]: /terraform/cloud-docs/users-teams-organizations/organizations
[teams]: /terraform/cloud-docs/users-teams-organizations/teams
[invite]: /terraform/cloud-docs/users-teams-organizations/organizations#users
[owners]: /terraform/cloud-docs/users-teams-organizations/teams#the-owners-team

# Users

User accounts belong to individual people. Each user can be part of one or more [teams](/terraform/cloud-docs/users-teams-organizations/teams), which are granted permissions on workspaces within an organization. A user can be a member of multiple [organizations][].

## API
Use the [Account API](/terraform/cloud-docs/api-docs/account) to get account details, update account information, and change your password.

<!-- BEGIN: TFC:only -->

## Log in with a HashiCorp Cloud Platform account

We recommend using a [HashiCorp Cloud Platform (HCP)](https://portal.cloud.hashicorp.com/sign-up) account to log in to HCP Terraform. Your HCP Account grants access to every HashiCorp product and the Terraform Registry. If you use an HCP Account, you manage account settings like multi-factor authentication and password resets from within HCP instead of the HCP Terraform UI.

To log in with your HCP account, go to the [Sign In to HCP Terraform](https://app.terraform.io/) page and click **Continue with HCP account**. HCP Terraform may ask if you want to link your account.

### Linking HCP and HCP Terraform accounts

The first time you log in with your HCP credentials, HCP Terraform searches for an existing HCP Terraform account with the same email address. If you have an unlinked account, HCP Terraform asks if you want to link it to your HCP account. Otherwise, if no account matches your HCP account's email address, HCP Terraform creates and automatically links a new HCP Terraform account to your HCP account.

> **Note**: You can only log in with your HCP credentials after linking your HCP and HCP Terraform accounts. We do not recommend linking your account if you use an SSO provider to log in to HCP Terraform because linking your account may conflict with your existing SSO configuration.

The only way to log in with your old HCP Terraform credentials is to unlink your HCP Terraform and HCP accounts. If HCP Terraform generated an account for you, you cannot unlink that account from your HCP account. You can unlink a pre-existing HCP Terraform account on the [HCP Account Linking page](#hcp-account-linking) in your **Account settings**.

<!-- END: TFC:only -->

## Creating an account

To use HCP Terraform or Enterprise, you must create an account through one of the following methods:

- **Invitation Email:** When a user sends you an invitation to join an existing HCP Terraform organization, the email includes a sign-up link. After you create an account, you can automatically join that organization and can begin using HCP Terraform.
- **Sign-Up Page:** Creating an account requires a username, an email address, and a password. For HCP Terraform, go to [`https://app.terraform.io/public/signup/account`](https://app.terraform.io/public/signup/account). For Terraform Enterprise, go to `https://<TFE HOSTNAME>/public/signup/account`. After you create an account, you do not belong to any organizations. To begin using HCP Terraform, you can either [create an organization](/terraform/cloud-docs/users-teams-organizations/organizations#creating-organizations) or ask an organization owner to send you an invitation email to join their organization.

<!-- BEGIN: TFC:only -->

We recommend logging into HCP Terraform [with your HCP account](#log-in-with-your-hashicorp-cloud-platform-account) instead of creating a separate HCP Terraform account.

<!-- END: TFC:only -->

## Joining organizations and teams

An organization owner or a user with [**Manage Membership**](/terraform/cloud-docs/users-teams-organizations/permissions#manage-membership) permissions enabled must [invite you to join their organization](/terraform/cloud-docs/users-teams-organizations/organizations#users) and [add you to one or more teams](/terraform/cloud-docs/users-teams-organizations/teams/manage#manage-team-membership).

[permissions-citation]: #intentionally-unused---keep-for-maintainers

HCP Terraform sends user invitations by email. If the invited email address matches an existing HCP Terraform account, the invitee can join the organization with that account. Otherwise, they must create a new account and then join the organization.

## Site admin permissions

On Terraform Enterprise instances, some user accounts have a special site admin permission that allows them to administer the entire instance.

Admin permissions are distinct from normal organization-level permissions, and they apply to a different set of UI controls and API endpoints. Admin users can administer any resource across the instance when using the site admin pages or the [admin API](/terraform/enterprise/api-docs/admin), but they have normal user permissions when using an organization's standard UI controls and API endpoints. These normal user permissions are determined by team membership.

Refer to [Administering Terraform Enterprise](/terraform/enterprise/admin) for more details.

## Account settings

To view your settings page, click your user icon and select **Account settings**. Your **Profile** page appears, showing your username, email address, and avatar.

### Profile

Click **Profile** in the sidebar to view and edit the username and email address associated with your HCP Terraform account.

~> **Important:** HCP Terraform includes your username in URL paths to resources. If external systems make requests to these resources, you must update them before you change your username.

HCP Terraform uses [Gravatar](http://en.gravatar.com) to display a user icon if you have associated one with your email address. Refer to the [Gravatar documentation](http://en.gravatar.com/support/) for details about changing your user icon.

### Sessions

Click **Sessions** in the sidebar to view a list of sessions associated with your HCP Terraform account. You can revoke any sessions you do not recognize.

<!-- BEGIN: TFC:only -->

There are two types of Terraform accounts, standalone HCP Terraform accounts and HCP Terraform accounts linked to HCP accounts.

### Idle session timeout

HCP Terraform automatically terminates user sessions if there has been no end-user activity for a certain time period:

- Standalone HCP Terraform accounts can stay idle and valid for up to 14 days by default
- HCP Terraform accounts linked to an HCP account follow the HCP defaults and can stay idle for 1 hour by default

After HCP Terraform terminates a session, you can resume it by logging back in through the HCP Terraform portal.  This is a security measure to prevent unauthorized access to unmonitored devices.

-> **Note:** HCP Terraform organization owners can reduce the idle session timeout for an organization in the authentication settings for standalone HCP Terraform accounts, but cannot modify settings for HCP Terraform accounts linked to HCP accounts.

### Forced re-authentication

Forced re-authentication (e.g., “remember for”) makes a user re-authenticate, regardless of activity.  This is a security measure to force a new identity verification to access sensitive IT and data managed by HCP Terraform.  In this case, the user must re-authenticate their credentials and may be asked to verify 2FA/MFA again.

- By default, standalone HCP Terraform accounts are forced to re-authenticate every 14 days
- By default, HCP Terraform accounts linked to an HCP account follow the HCP defaults and are forced to re-authenticate every 48 hours

-> **Note:** HCP Terraform organization owners can reduce the idle session timeout for standalone HCP Terraform accounts, but cannot modify settings for HCP Terraform accounts linked to HCP accounts.

### Impact to user experience

The default re-authentication defaults force users to re-authenticate at the beginning of each work week (Monday through Friday). Note that several actions immediately terminate active sessions, including:

* Manually logging out of the HCP or HCP Terraform portals
* Clearing browser session/cookies
* Closing all active browser windows

Any of these actions requires you to re-authenticate regardless of session timeout settings.

<!-- END: TFC:only -->

### Organizations

Click **Organizations** in the sidebar to view a list of the organizations where you are a member. If you are on the [owners team][owners], the organization is marked with an **OWNER** badge.

To leave an organization, click the ellipses (**...**) next to the organization and select **Leave organization**. You do not need permission from the owners to leave an organization, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or [delete the organization](/terraform/cloud-docs/users-teams-organizations/organizations#general).

### Password

Click **Password** in the sidebar to change your password.

-> **Note:** Password management is not available if your Terraform Enterprise instance uses [SAML single sign on](/terraform/enterprise/saml/configuration).
-> **Note:** Passwords must be at least 10 characters in length, and you can use any type of character. Password management is not available if your Terraform Enterprise instance uses [SAML single sign on](/terraform/enterprise/saml/configuration).

### Two-factor authentication

Click **Two Factor Authentication** in the sidebar to enable two-factor authentication. Two-factor authentication requires a TOTP-compliant application or an SMS-capable phone number. An organization can set policies that require two-factor authentication.

Refer to [Two-Factor Authentication](/terraform/cloud-docs/users-teams-organizations/2fa) for details.

<!-- BEGIN: TFC:only -->

### HCP account linking

Click **HCP Account Linking** in the sidebar to unlink your HCP Terraform from your HCP Account. You cannot unlink an account that HCP Terraform autogenerated during the linking process. Refer to [Linked HCP and HCP Terraform Accounts](#linked-hcp-and-hcp-terraform-accounts) for more details.

After you unlink, you can begin using your HCP Terraform credentials to log in. You cannot log in with your HCP account again unless you re-link it to your HCP Terraform account.

### SSO identities

Click **SSO Identities** in the sidebar to review and [remove SSO identity links](/terraform/cloud-docs/users-teams-organizations/single-sign-on/linking-user-account#remove-sso-identity-link) associated with your account.

You have an SSO identity for every SSO-enabled HCP Terraform organization. HCP Terraform links each SSO identity to a single HCP Terraform user account. This link determines which account you can use to access each organization.

<!-- END: TFC:only -->

### Tokens

Click **Tokens** in the sidebar to create, manage, and revoke API tokens. HCP Terraform has three kinds of API tokens: user, team, and organization. Users can be members of multiple organizations, so user tokens work with any organization where the associated user is a member. Refer to [API Tokens](/terraform/cloud-docs/users-teams-organizations/api-tokens) for details.

API tokens are required for the following tasks:

- Authenticating with the [HCP Terraform API](/terraform/cloud-docs/api-docs). API calls require an `Authorization: Bearer <TOKEN>` HTTP header.
- Authenticating with the [HCP Terraform CLI integration](/terraform/cli/cloud/settings) or the [`remote` backend](/terraform/language/settings/backends/remote). These require a token in the CLI configuration file or in the backend configuration.
- Using [private modules](/terraform/cloud-docs/registry/using) in command-line runs on local machines. This requires [a token in the CLI configuration file](/terraform/cloud-docs/registry/using#authentication).

Protect your tokens carefully because they contain the same permissions as your user account. For example, if you belong to a team with permission to read and write variables for a workspace, another user could use your API token to authenticate as your user account and also edit variables in that workspace. Refer to [permissions](/terraform/cloud-docs/users-teams-organizations/permissions) for more details.

We recommend protecting your tokens by creating them with an expiration date and time. Refer to [API Token Expiration](/terraform/cloud-docs/users-teams-organizations/api-tokens#token-expiration) for details.

#### Creating a token

 To create a new token:
  1. Click **Create an API token**. The **Create API token** box appears.
  1. Enter a **Description** that explains what the token is for and click **Create API token**.
  1. You can optionally enter the token's expiration date or time, or create a token that never expires. The UI displays a token's expiration date and time in your current time zone.
  1. Copy your token from the box and save it in a secure location. HCP Terraform only displays the token once, right after you create it. If you lose it, you must revoke the old token and create a new one.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

#### Revoking a token

To revoke a token, click the **trash can** next to it. That token will no longer be able to authenticate as your user account.

~> **Note**: HCP Terraform does not revoke a user API token's access to an organization when you remove the user from an SSO Identity Provider as the user may still be a member of the organization. To remove access to a user's API token, remove the user from the organization in the UI or with the [Terraform Enterprise provider](https://registry.terraform.io/providers/hashicorp/tfe/latest).

### GitHub app OAuth token

Click **Tokens** in the sidebar to manage your GitHub App token. This token lets you connect a workspaces to an available GitHub App installation.

~> **Note:** Only an HCP Terraform user can own a GitHub App token. Team and Organization API tokens are not able to own a GitHub App token.

A GitHub App token lets you:
- Connect workspaces, policy sets, and registry modules to a GitHub App installation with the [HCP Terraform API](/terraform/cloud-docs/api-docs) and UI.
- View available GitHub App installations with the [HCP Terraform API](/terraform/cloud-docs/api-docs) and UI.

After generating this token, you can use it to view information about your available installations for the Terraform Cloud GitHub App.

#### Creating a GitHub app token

To create a GitHub App token, click **Create a GitHub App token**. The **GitHub App authorization pop-up window** appears requesting authorization of the Terraform Cloud GitHub App.

~> **Note:** This does not grant HCP Terraform access to repositories.

#### Revoking a GitHub app token

To revoke the GitHub App token, click the **ellipses button (...)**. The dropdown menu appears. Click the **Delete Token** option. This triggers a confirmation window to appear, which asks you to confirm that you want to revoke the token. Once confirmed, the token is revoked and you can no longer view GitHub App installations.

#### Additional resources

- [GitHub App permissions in HCP Terraform](/terraform/cloud-docs/vcs/github-app#github-permissions)

page title  Users   HCP Terraform description       Create an account  edit settings  set up two factor authentication  create API   tokens  and more        organizations    terraform cloud docs users teams organizations organizations  teams    terraform cloud docs users teams organizations teams  invite    terraform cloud docs users teams organizations organizations users  owners    terraform cloud docs users teams organizations teams the owners team    Users  User accounts belong to individual people  Each user can be part of one or more  teams   terraform cloud docs users teams organizations teams   which are granted permissions on workspaces within an organization  A user can be a member of multiple  organizations         API Use the  Account API   terraform cloud docs api docs account  to get account details  update account information  and change your password        BEGIN  TFC only         Log in with a HashiCorp Cloud Platform account  We recommend using a  HashiCorp Cloud Platform  HCP   https   portal cloud hashicorp com sign up  account to log in to HCP Terraform  Your HCP Account grants access to every HashiCorp product and the Terraform Registry  If you use an HCP Account  you manage account settings like multi factor authentication and password resets from within HCP instead of the HCP Terraform UI   To log in with your HCP account  go to the  Sign In to HCP Terraform  https   app terraform io   page and click   Continue with HCP account    HCP Terraform may ask if you want to link your account       Linking HCP and HCP Terraform accounts  The first time you log in with your HCP credentials  HCP Terraform searches for an existing HCP Terraform account with the same email address  If you have an unlinked account  HCP Terraform asks if you want to link it to your HCP account  Otherwise  if no account matches your HCP account s email address  HCP Terraform creates and automatically links a new HCP Terraform account to your HCP account       Note    You can only log in with your HCP credentials after linking your HCP and HCP Terraform accounts  We do not recommend linking your account if you use an SSO provider to log in to HCP Terraform because linking your account may conflict with your existing SSO configuration    The only way to log in with your old HCP Terraform credentials is to unlink your HCP Terraform and HCP accounts  If HCP Terraform generated an account for you  you cannot unlink that account from your HCP account  You can unlink a pre existing HCP Terraform account on the  HCP Account Linking page   hcp account linking  in your   Account settings          END  TFC only         Creating an account  To use HCP Terraform or Enterprise  you must create an account through one of the following methods       Invitation Email    When a user sends you an invitation to join an existing HCP Terraform organization  the email includes a sign up link  After you create an account  you can automatically join that organization and can begin using HCP Terraform      Sign Up Page    Creating an account requires a username  an email address  and a password  For HCP Terraform  go to   https   app terraform io public signup account   https   app terraform io public signup account   For Terraform Enterprise  go to  https    TFE HOSTNAME  public signup account   After you create an account  you do not belong to any organizations  To begin using HCP Terraform  you can either  create an organization   terraform cloud docs users teams organizations organizations creating organizations  or ask an organization owner to send you an invitation email to join their organization        BEGIN  TFC only      We recommend logging into HCP Terraform  with your HCP account   log in with your hashicorp cloud platform account  instead of creating a separate HCP Terraform account        END  TFC only         Joining organizations and teams  An organization owner or a user with    Manage Membership     terraform cloud docs users teams organizations permissions manage membership  permissions enabled must  invite you to join their organization   terraform cloud docs users teams organizations organizations users  and  add you to one or more teams   terraform cloud docs users teams organizations teams manage manage team membership     permissions citation    intentionally unused   keep for maintainers  HCP Terraform sends user invitations by email  If the invited email address matches an existing HCP Terraform account  the invitee can join the organization with that account  Otherwise  they must create a new account and then join the organization      Site admin permissions  On Terraform Enterprise instances  some user accounts have a special site admin permission that allows them to administer the entire instance   Admin permissions are distinct from normal organization level permissions  and they apply to a different set of UI controls and API endpoints  Admin users can administer any resource across the instance when using the site admin pages or the  admin API   terraform enterprise api docs admin   but they have normal user permissions when using an organization s standard UI controls and API endpoints  These normal user permissions are determined by team membership   Refer to  Administering Terraform Enterprise   terraform enterprise admin  for more details      Account settings  To view your settings page  click your user icon and select   Account settings    Your   Profile   page appears  showing your username  email address  and avatar       Profile  Click   Profile   in the sidebar to view and edit the username and email address associated with your HCP Terraform account        Important    HCP Terraform includes your username in URL paths to resources  If external systems make requests to these resources  you must update them before you change your username   HCP Terraform uses  Gravatar  http   en gravatar com  to display a user icon if you have associated one with your email address  Refer to the  Gravatar documentation  http   en gravatar com support   for details about changing your user icon       Sessions  Click   Sessions   in the sidebar to view a list of sessions associated with your HCP Terraform account  You can revoke any sessions you do not recognize        BEGIN  TFC only      There are two types of Terraform accounts  standalone HCP Terraform accounts and HCP Terraform accounts linked to HCP accounts        Idle session timeout  HCP Terraform automatically terminates user sessions if there has been no end user activity for a certain time period      Standalone HCP Terraform accounts can stay idle and valid for up to 14 days by default   HCP Terraform accounts linked to an HCP account follow the HCP defaults and can stay idle for 1 hour by default  After HCP Terraform terminates a session  you can resume it by logging back in through the HCP Terraform portal   This is a security measure to prevent unauthorized access to unmonitored devices        Note    HCP Terraform organization owners can reduce the idle session timeout for an organization in the authentication settings for standalone HCP Terraform accounts  but cannot modify settings for HCP Terraform accounts linked to HCP accounts       Forced re authentication  Forced re authentication  e g    remember for   makes a user re authenticate  regardless of activity   This is a security measure to force a new identity verification to access sensitive IT and data managed by HCP Terraform   In this case  the user must re authenticate their credentials and may be asked to verify 2FA MFA again     By default  standalone HCP Terraform accounts are forced to re authenticate every 14 days    By default  HCP Terraform accounts linked to an HCP account follow the HCP defaults and are forced to re authenticate every 48 hours       Note    HCP Terraform organization owners can reduce the idle session timeout for standalone HCP Terraform accounts  but cannot modify settings for HCP Terraform accounts linked to HCP accounts       Impact to user experience  The default re authentication defaults force users to re authenticate at the beginning of each work week  Monday through Friday   Note that several actions immediately terminate active sessions  including     Manually logging out of the HCP or HCP Terraform portals   Clearing browser session cookies   Closing all active browser windows  Any of these actions requires you to re authenticate regardless of session timeout settings        END  TFC only          Organizations  Click   Organizations   in the sidebar to view a list of the organizations where you are a member  If you are on the  owners team  owners   the organization is marked with an   OWNER   badge   To leave an organization  click the ellipses           next to the organization and select   Leave organization    You do not need permission from the owners to leave an organization  but you cannot leave if you are the last member of the owners team  Either add a new owner and then leave  or  delete the organization   terraform cloud docs users teams organizations organizations general        Password  Click   Password   in the sidebar to change your password        Note    Password management is not available if your Terraform Enterprise instance uses  SAML single sign on   terraform enterprise saml configuration        Note    Passwords must be at least 10 characters in length  and you can use any type of character  Password management is not available if your Terraform Enterprise instance uses  SAML single sign on   terraform enterprise saml configuration        Two factor authentication  Click   Two Factor Authentication   in the sidebar to enable two factor authentication  Two factor authentication requires a TOTP compliant application or an SMS capable phone number  An organization can set policies that require two factor authentication   Refer to  Two Factor Authentication   terraform cloud docs users teams organizations 2fa  for details        BEGIN  TFC only          HCP account linking  Click   HCP Account Linking   in the sidebar to unlink your HCP Terraform from your HCP Account  You cannot unlink an account that HCP Terraform autogenerated during the linking process  Refer to  Linked HCP and HCP Terraform Accounts   linked hcp and hcp terraform accounts  for more details   After you unlink  you can begin using your HCP Terraform credentials to log in  You cannot log in with your HCP account again unless you re link it to your HCP Terraform account       SSO identities  Click   SSO Identities   in the sidebar to review and  remove SSO identity links   terraform cloud docs users teams organizations single sign on linking user account remove sso identity link  associated with your account   You have an SSO identity for every SSO enabled HCP Terraform organization  HCP Terraform links each SSO identity to a single HCP Terraform user account  This link determines which account you can use to access each organization        END  TFC only          Tokens  Click   Tokens   in the sidebar to create  manage  and revoke API tokens  HCP Terraform has three kinds of API tokens  user  team  and organization  Users can be members of multiple organizations  so user tokens work with any organization where the associated user is a member  Refer to  API Tokens   terraform cloud docs users teams organizations api tokens  for details   API tokens are required for the following tasks     Authenticating with the  HCP Terraform API   terraform cloud docs api docs   API calls require an  Authorization  Bearer  TOKEN   HTTP header    Authenticating with the  HCP Terraform CLI integration   terraform cli cloud settings  or the   remote  backend   terraform language settings backends remote   These require a token in the CLI configuration file or in the backend configuration    Using  private modules   terraform cloud docs registry using  in command line runs on local machines  This requires  a token in the CLI configuration file   terraform cloud docs registry using authentication    Protect your tokens carefully because they contain the same permissions as your user account  For example  if you belong to a team with permission to read and write variables for a workspace  another user could use your API token to authenticate as your user account and also edit variables in that workspace  Refer to  permissions   terraform cloud docs users teams organizations permissions  for more details   We recommend protecting your tokens by creating them with an expiration date and time  Refer to  API Token Expiration   terraform cloud docs users teams organizations api tokens token expiration  for details        Creating a token   To create a new token    1  Click   Create an API token    The   Create API token   box appears    1  Enter a   Description   that explains what the token is for and click   Create API token      1  You can optionally enter the token s expiration date or time  or create a token that never expires  The UI displays a token s expiration date and time in your current time zone    1  Copy your token from the box and save it in a secure location  HCP Terraform only displays the token once  right after you create it  If you lose it  you must revoke the old token and create a new one     permissions citation    intentionally unused   keep for maintainers       Revoking a token  To revoke a token  click the   trash can   next to it  That token will no longer be able to authenticate as your user account        Note    HCP Terraform does not revoke a user API token s access to an organization when you remove the user from an SSO Identity Provider as the user may still be a member of the organization  To remove access to a user s API token  remove the user from the organization in the UI or with the  Terraform Enterprise provider  https   registry terraform io providers hashicorp tfe latest        GitHub app OAuth token  Click   Tokens   in the sidebar to manage your GitHub App token  This token lets you connect a workspaces to an available GitHub App installation        Note    Only an HCP Terraform user can own a GitHub App token  Team and Organization API tokens are not able to own a GitHub App token   A GitHub App token lets you    Connect workspaces  policy sets  and registry modules to a GitHub App installation with the  HCP Terraform API   terraform cloud docs api docs  and UI    View available GitHub App installations with the  HCP Terraform API   terraform cloud docs api docs  and UI   After generating this token  you can use it to view information about your available installations for the Terraform Cloud GitHub App        Creating a GitHub app token  To create a GitHub App token  click   Create a GitHub App token    The   GitHub App authorization pop up window   appears requesting authorization of the Terraform Cloud GitHub App        Note    This does not grant HCP Terraform access to repositories        Revoking a GitHub app token  To revoke the GitHub App token  click the   ellipses button          The dropdown menu appears  Click the   Delete Token   option  This triggers a confirmation window to appear  which asks you to confirm that you want to revoke the token  Once confirmed  the token is revoked and you can no longer view GitHub App installations        Additional resources     GitHub App permissions in HCP Terraform   terraform cloud docs vcs github app github permissions


terraform page title Organizations overview Organizations are partitions in HCP Terraform and Terraform Enterprise that let teams within a business unit collaborate on infrastructure as code projects Organizations contain one or more projects which contain one or more workspaces teams terraform cloud docs users teams organizations teams users terraform cloud docs users teams organizations users

Answer:
---
page_title: Organizations overview
description: >-
  Organizations are partitions in HCP Terraform and Terraform Enterprise that let teams within a business unit collaborate on infrastructure as code projects. Organizations contain one or more projects, which contain one or more workspaces.
---

[teams]: /terraform/cloud-docs/users-teams-organizations/teams

[users]: /terraform/cloud-docs/users-teams-organizations/users

[owners]: /terraform/cloud-docs/users-teams-organizations/teams#the-owners-team

# Organizations overview

This topic provides overview information about how to create and manage organizations in HCP Terraform and Terraform Enterprise. An organization contains one or more projects.

## Requirements

The **admin** permission preset must be enabled on your profile to create and manage organizations in the HCP Terraform UI. Refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions) for additional information.

## API and Terraform Enterprise Provider

In addition to the HCP Terraform UI, you can use the following methods to manage organizations:
- [Organizations API](/terraform/cloud-docs/api-docs/organizations)
- The `tfe` provider [`tfe_organization`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/organization) resource

## Selecting organizations

HCP Terraform displays your current organization in the bottom left of the sidebar. To select an organization:

1. Click the current organization name to view a list of all the organizations where you are a member.
1. Click an organization to select it. HCP Terraform displays list of workspaces within that organization.

## Joining and leaving organizations

To join an organization, the organization [owners][] or a user with specific [team management](/terraform/cloud-docs/users-teams-organizations/permissions#team-management-permissions) permissions must invite you, and you must accept the emailed invitation. [Learn more](#users).

[permissions-citation]: #intentionally-unused---keep-for-maintainers

To leave an organization:

1. Click the Terraform logo in the upper left corner to navigate to the **Organizations** page.
1. Click the ellipses (**...**) next to the organization and select **Leave organization**.

You do not need permission from the owners to leave an organization, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or [delete the organization](/terraform/cloud-docs/users-teams-organizations/organizations#general).

## Creating organizations

On Terraform Enterprise, administrators can restrict your ability to create organizations. Refer to [Administration: General Settings](/terraform/enterprise/admin/application/general#organization-creation) for details.

On HCP Terraform, any user can create a new organization. If you do not belong to any organizations, HCP Terraform prompts you to create one the first time you log in. To create an organization:

1. Click the current organization name and select **Create new organization**. The **Create a new organization** page appears.
1. Enter a unique **Organization name** Organization names can include numbers, letters, underscores (`_`), and hyphens (`-`).
1. Provide an **Email address** to receive notifications about the organization.
1. Click **Create organization**.

HCP Terraform shows the new organization and prompts you to create a new workspace. You can also [invite other users](#users) to join the organization.

## Managed resources

Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces.

HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. Each [resource](/terraform/language/resources/syntax) instance in the state equals one managed resource. HCP Terraform includes resources in modules and each resource created with the `count` or `for_each` meta-arguments. HCP Terraform does not include [data sources](/terraform/language/data-sources) in the count. Refer to [Managed Resources Count](/terraform/cloud-docs/workspaces/state#managed-resources-count) in the workspace state documentation for more details.

You can view your organization's managed resource count on the **Usage** page.

## Create and manage reserved tags

~> **Reserved tags is in private beta and unavailable for some users.** Contact your HashiCorp representative for information about participating in the private beta.

Tags are key-value pairs that you can apply to projects and workspaces. Tags help you organize your projects and resources, as well as track resource consumption. Refer to the following topics for information about creating and managing tags attached to projects and workspaces:

- [Create a project](/terraform/cloud-docs/projects/manage#create-a-project)
- [Create workspace tags](/terraform/cloud-docs/workspaces/tags)

You can define reserved tag keys for your organization so that project and workspace managers can use consistent labels.

1. Click on **Tags** in the sidebar to view all tags in your organization.
1. Click on the **Reserved Keys** tab. You can perform the following actions:
   1. Use the search bar to find a specific tag key.
   1. Click on a column header to sort the table.
   1. Click on the ellipses menu to open the management options for each tag key.
   1. Click **New tag key** to define a new key.

You can also view single-value tags that workspace managers added directly to their workspaces. Refer to [Tags](#tags) in the organization settings reference for additional information.

## Managing settings

To view and manage an organization's settings, click **Settings**.

The contents of the organization settings depends on your permissions within the organization. All users can review the organization's contact email, view the membership of any teams they belong to, and view the organization's authentication policy. [Organization owners][owners] can view and manage the entire list of organization settings. Refer to [Organization Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions) for details.

You may be able to manage the following organization settings.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

### Organization settings

#### General

Review the organization name and contact email. Organization owners can choose to change the organization name, contact email, and the default execution mode, or delete the organization. When an organization owner updates the default execution mode, all workspaces configured to [inherit this value](/terraform/cloud-docs/workspaces/settings#execution-mode) will be affected.

Organization owners can also choose whether [workspace administrators](/terraform/cloud-docs/users-teams-organizations/permissions#workspace-admins) can delete workspaces that are managing resources. Deleting a workspace with resources under management introduces risk because Terraform can no longer track or manage the infrastructure. The workspace's users must manually delete any remaining resources or [import](/terraform/cli/commands/import) them into another Terraform workspace.

Organization owners using HCP Terraform Plus edition can choose whether members with [module management permissions](/terraform/cloud-docs/users-teams-organizations/permissions#manage-private-registry) can [generate module tests](/terraform/cloud-docs/registry/test#generated-module-tests).

##### Renaming an organization

!> **Warning:** Deleting or renaming an organization can be very disruptive. We strongly recommend against deleting or renaming organizations with active members.

To rename an organization that manages infrastructure:

1. Alert all members of the organization about the name change.
1. Cancel in progress and pending runs or wait for them to finish. HCP Terraform cannot change the name of an organization with runs in progress.
1. Lock all workspaces to ensure that no new runs will start before you change the name.
1. Rename the organization.
1. Update all components using the HCP Terraform API to the new organization name. This includes Terraform's `cloud` block CLI integration, the `tfe` Terraform provider, and any external API integrations.
1. Unlock workspaces and resume normal operations.

#### Plan & Billing

Review the organization's plan and any invoices for previous plan payments. Organization owners can also upgrade to one of HCP Terraform's paid plans, downgrade to a free plan, or begin a free trial of paid features.

#### Tags

Click the **Tags** tab in the **Tags Management** screen to view single-value tags that workspace managers added directly to their workspaces. For information about key-value tag keys, refer to [Create and manage reserved tags](#create-and-manage-reserved-tags).

You can perform the following actions in the **Tags** tab:

1. Search for a tag key or value.
1. Click on a column header to sort tags.

#### Teams

@include 'tfc-package-callouts/team-management.mdx'

All users in an organization can access the **Teams** page, which displays a list of [teams][] within the organization.

Organization owners and users with the [include secret teams permission](/terraform/cloud-docs/users-teams-organizations/permissions#include-secret-teams) can:
  * view all [secret teams](/terraform/cloud-docs/users-teams-organizations/teams/manage#team-visibility)
  * view each team's membership
  * manage team API tokens

HCP Terraform restricts team creation, team deletion, and management of team API tokens to organization owners and users with the [manage teams](/terraform/cloud-docs/users-teams-organizations/permissions#manage-teams) permission. Organization owners and users with the [manage membership](/terraform/cloud-docs/users-teams-organizations/permissions#manage-membership) permission can manage team membership. Remember that users must accept their organization invitations before you can add them to a team.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

#### Users

Organization owners and users with [manage membership](/terraform/cloud-docs/users-teams-organizations/permissions#manage-membership) permissions can invite HCP Terraform users into the organization, cancel invitations, and remove existing members.

The list of users is separated into one tab for active users and one tab for invited users who have not yet accepted their invitations. For active users, the list includes usernames, email addresses, avatar icons, two-factor authentication status, and current team memberships. Use the **Search by username or email** field to filter these lists.

User invitations are always sent by email; you cannot invite someone using their HCP Terraform username. To invite a user to an organization:

1. Click **Invite a user**. The **invite a user** box appears.
1. Enter the user's email address and optionally add them to one or more teams. If the user accepts the invitation, HCP Terraform automatically adds them to the specified teams.

All permissions in HCP Terraform are managed through teams. Users can join an organization without belonging to any teams, but they cannot use Terraform Cloud features until they belong to a team. Refer to [permissions](/terraform/cloud-docs/users-teams-organizations/permissions) for details.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

#### Variable Sets

View all of the available variable sets and their variables. Users with [`read and write variables` permissions](/terraform/cloud-docs/users-teams-organizations/permissions#general-workspace-permissions) can also create variable sets and assign them to one or more workspaces.

Variable sets let you reuse the same variables across multiple workspaces in the organization. For example, you could define a variable set of provider credentials and automatically apply it to several workspaces, rather than manually defining credential variables in each. Changes to variable sets instantly apply to all appropriate workspaces, saving time and reducing errors from manual updates.

Refer to the [variables overview](/terraform/cloud-docs/workspaces/variables) documentation for details about variable types, scope, and precedence. Refer to [managing variables](/terraform/cloud-docs/workspaces/variables/managing-variables) for details about how to create and manage variable sets.

#### Health

@include 'tfc-package-callouts/health-assessments.mdx'

HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations:
- Drift detection determines whether your real-world infrastructure matches your Terraform configuration. Drift detection requires Terraform version 0.15.4+.
- Continuous validation determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. Continuous validation requires Terraform version 1.3.0+.

You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings. Refer to [Health](/terraform/cloud-docs/workspaces/health) in the workspaces documentation for more details.

#### Runs
From the Workspaces page, click **Settings** in the sidebar, then **Runs** to view all of the current runs in your organization's workspaces. The **Runs** page displays:
- The name of the run
- The run's ID
- What triggered the run
- The workspace and project where the run is taking place
- When the latest change in the run occurred
- A button allowing you to cancel that run

You can apply the following filters to limit the runs HCP Terraform displays:
- Click **Needs Attention** to display runs that require user input to continue, such as approving a plan or overriding a policy.
- Click **Running** to display runs that are in progress.
- Click **On Hold** to display paused runs.

For precise filtering, click **More filters** and check the boxes to filter runs by specific [run statuses](/terraform/cloud-docs/run/states), [run operations](/terraform/cloud-docs/run/modes-and-options), workspaces, or [agent pools](/terraform/cloud-docs/agents/agent-pools). Click **Apply filters** to list the runs that match your criteria.

You can dismiss any of your filtering criteria by clicking the **X** next to the filter name above the table displaying your runs.

For more details about run states, refer to [Run States and Stages](/terraform/cloud-docs/run/states).

### Integrations

#### Cost Estimation

Enable and disable the [cost estimation](/terraform/cloud-docs/cost-estimation) feature for all workspaces.

#### Policies

@include 'tfc-package-callouts/policies.mdx'

Policies let you define and enforce rules for Terraform runs. You can write them using either the [Sentinel](/terraform/cloud-docs/policy-enforcement/sentinel) or [Open Policy Agent (OPA)](/terraform/cloud-docs/policy-enforcement/opa) policy-as-code frameworks and then group them into policy sets that you can apply to workspaces in your organization. To create policies and policy sets, you must have [permission to manage policies](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions).

#### Policy Sets

@include 'tfc-package-callouts/policies.mdx'

Create groups of policies and enforce those policy sets globally or on specific [projects](/terraform/cloud-docs/projects/manage) and workspaces. You can create policy sets through the Terraform API, by connecting a VCS repository containing policies, or directly in HCP Terraform. To create policies and policy sets, you must have [permission to manage policies](/terraform/cloud-docs/users-teams-organizations/permissions#organization-permissions).

Refer to [Managing Policy Sets](/terraform/cloud-docs/policy-enforcement/manage-policy-sets) for details.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

#### Run Tasks

@include 'tfc-package-callouts/run-tasks.mdx'

Manage the run tasks that you can add to workspaces within the organization. [Run tasks](/terraform/cloud-docs/workspaces/settings/run-tasks) let you integrate third-party tools and services at specific stages in the HCP Terraform run lifecycle.

### Security

#### Agents

@include 'tfc-package-callouts/agents.mdx'

Create and manage [HCP Terraform agent pools](/terraform/cloud-docs/agents). HCP Terraform agents let HCP Terraform communicate with isolated, private, or on-premises infrastructure. This is useful for on-premises infrastructure types such as vSphere, Nutanix, OpenStack, enterprise networking providers, and infrastructure within a protected enclave.

#### API Tokens

Organization owners can set up a special [Organization API Token](/terraform/cloud-docs/users-teams-organizations/api-tokens) that is not associated with a specific user or team.

#### Authentication

Organization owners can determine when users must reauthenticate and require [two-factor authentication](/terraform/cloud-docs/users-teams-organizations/2fa) for all members of the organization.

#### SSH Keys

Manage [SSH keys for cloning Git-based modules](/terraform/cloud-docs/workspaces/settings/ssh-keys) during Terraform runs. This does not include keys to access a connected VCS provider.

#### SSO

Organization owners can set up an SSO provider for the organization.

### Version Control

#### VCS General

Configure [Automatically cancel plan-only runs triggered by outdated commits](/terraform/cloud-docs/users-teams-organizations/organizations/vcs-speculative-plan-management) to manage the setting.

#### VCS Events

-> **Note:** This feature is in beta.

Review the event logs for GitLab.com connections.

#### VCS Providers

Configure [VCS providers](/terraform/cloud-docs/vcs) to use in the organization. You must have [permission to manage VCS settings](/terraform/cloud-docs/users-teams-organizations/permissions).

[permissions-citation]: #intentionally-unused---keep-for-maintainers

### Destruction and Deletion

#### Data Retention Policies

<EnterpriseAlert>
Data retention policies are exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise.
</EnterpriseAlert>

An organization owner can set or override the following data retention policies:

- **Admin default policy**
- **Do not auto-delete**
- **Auto-delete data**

Setting the data retention policy to **Admin default policy** disables the other data retention policy settings.

By default, the **Do not auto-delete** option is enabled for an organization. This option directs Terraform Enterprise to retain data associated with configuration and state versions, but organization owners can define configurable data retention policies that allow Terraform to _soft delete_ the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform can delete the object after a set number of days.

Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection process begins, you can restore soft deleted objects using the APIs described in the [configuration version documentation](/terraform/enterprise/api-docs/configuration-versions) and the [state version documentation](/terraform/enterprise/api-docs/state-versions). Terraform permanently deletes the archivist storage after the garbage collection grace period elapses.

The organization policy is the default policy applied to all workspaces, but members of individual workspaces can set overriding policies for their workspaces that take precedence over the organization policy.

## Trial Expired Organizations

HCP Terraform paid features are available as a free trial. When a free trial has expired, the organization displays a banner reading **TRIAL EXPIRED — Upgrade Required**.

Organizations with expired trials return to the feature set of a free organization, but they retain any data created as part of paid features. Specifically, HCP Terraform disables the following features:

- Teams other than `owners` and locks users who do not belong to the `owners` team out of the organization. HCP Terraform preserves team membership and permissions and re-enables them after you upgrade the organization.
- Sentinel policy checks. HCP Terraform preserves existing policies and policy sets and re-enables them after you upgrade the organization.
- Cost estimation.

page title  Organizations overview description       Organizations are partitions in HCP Terraform and Terraform Enterprise that let teams within a business unit collaborate on infrastructure as code projects  Organizations contain one or more projects  which contain one or more workspaces        teams    terraform cloud docs users teams organizations teams   users    terraform cloud docs users teams organizations users   owners    terraform cloud docs users teams organizations teams the owners team    Organizations overview  This topic provides overview information about how to create and manage organizations in HCP Terraform and Terraform Enterprise  An organization contains one or more projects      Requirements  The   admin   permission preset must be enabled on your profile to create and manage organizations in the HCP Terraform UI  Refer to  Permissions   terraform cloud docs users teams organizations permissions organization permissions  for additional information       API and Terraform Enterprise Provider  In addition to the HCP Terraform UI  you can use the following methods to manage organizations     Organizations API   terraform cloud docs api docs organizations    The  tfe  provider   tfe organization   https   registry terraform io providers hashicorp tfe latest docs resources organization  resource     Selecting organizations  HCP Terraform displays your current organization in the bottom left of the sidebar  To select an organization   1  Click the current organization name to view a list of all the organizations where you are a member  1  Click an organization to select it  HCP Terraform displays list of workspaces within that organization      Joining and leaving organizations  To join an organization  the organization  owners    or a user with specific  team management   terraform cloud docs users teams organizations permissions team management permissions  permissions must invite you  and you must accept the emailed invitation   Learn more   users     permissions citation    intentionally unused   keep for maintainers  To leave an organization   1  Click the Terraform logo in the upper left corner to navigate to the   Organizations   page  1  Click the ellipses           next to the organization and select   Leave organization      You do not need permission from the owners to leave an organization  but you cannot leave if you are the last member of the owners team  Either add a new owner and then leave  or  delete the organization   terraform cloud docs users teams organizations organizations general       Creating organizations  On Terraform Enterprise  administrators can restrict your ability to create organizations  Refer to  Administration  General Settings   terraform enterprise admin application general organization creation  for details   On HCP Terraform  any user can create a new organization  If you do not belong to any organizations  HCP Terraform prompts you to create one the first time you log in  To create an organization   1  Click the current organization name and select   Create new organization    The   Create a new organization   page appears  1  Enter a unique   Organization name   Organization names can include numbers  letters  underscores        and hyphens        1  Provide an   Email address   to receive notifications about the organization  1  Click   Create organization     HCP Terraform shows the new organization and prompts you to create a new workspace  You can also  invite other users   users  to join the organization        BEGIN  TFC only name managed resources         Managed resources  Your organization s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces   HCP Terraform reads all the workspaces  state files to determine the total number of managed resources  Each  resource   terraform language resources syntax  instance in the state equals one managed resource  HCP Terraform includes resources in modules and each resource created with the  count  or  for each  meta arguments  HCP Terraform does not include  data sources   terraform language data sources  in the count  Refer to  Managed Resources Count   terraform cloud docs workspaces state managed resources count  in the workspace state documentation for more details   You can view your organization s managed resource count on the   Usage   page        END  TFC only name managed resources         Create and manage reserved tags       Reserved tags is in private beta and unavailable for some users    Contact your HashiCorp representative for information about participating in the private beta   Tags are key value pairs that you can apply to projects and workspaces  Tags help you organize your projects and resources  as well as track resource consumption  Refer to the following topics for information about creating and managing tags attached to projects and workspaces      Create a project   terraform cloud docs projects manage create a project     Create workspace tags   terraform cloud docs workspaces tags   You can define reserved tag keys for your organization so that project and workspace managers can use consistent labels   1  Click on   Tags   in the sidebar to view all tags in your organization   1  Click on the   Reserved Keys   tab  You can perform the following actions     1  Use the search bar to find a specific tag key     1  Click on a column header to sort the table     1  Click on the ellipses menu to open the management options for each tag key     1  Click   New tag key   to define a new key   You can also view single value tags that workspace managers added directly to their workspaces  Refer to  Tags   tags  in the organization settings reference for additional information      Managing settings  To view and manage an organization s settings  click   Settings     The contents of the organization settings depends on your permissions within the organization  All users can review the organization s contact email  view the membership of any teams they belong to  and view the organization s authentication policy   Organization owners  owners  can view and manage the entire list of organization settings  Refer to  Organization Permissions   terraform cloud docs users teams organizations permissions organization permissions  for details   You may be able to manage the following organization settings    permissions citation    intentionally unused   keep for maintainers      Organization settings       General  Review the organization name and contact email  Organization owners can choose to change the organization name  contact email  and the default execution mode  or delete the organization  When an organization owner updates the default execution mode  all workspaces configured to  inherit this value   terraform cloud docs workspaces settings execution mode  will be affected   Organization owners can also choose whether  workspace administrators   terraform cloud docs users teams organizations permissions workspace admins  can delete workspaces that are managing resources  Deleting a workspace with resources under management introduces risk because Terraform can no longer track or manage the infrastructure  The workspace s users must manually delete any remaining resources or  import   terraform cli commands import  them into another Terraform workspace        BEGIN  TFC only name generated tests      Organization owners using HCP Terraform Plus edition can choose whether members with  module management permissions   terraform cloud docs users teams organizations permissions manage private registry  can  generate module tests   terraform cloud docs registry test generated module tests         END  TFC only name generated tests            Renaming an organization       Warning    Deleting or renaming an organization can be very disruptive  We strongly recommend against deleting or renaming organizations with active members   To rename an organization that manages infrastructure   1  Alert all members of the organization about the name change  1  Cancel in progress and pending runs or wait for them to finish  HCP Terraform cannot change the name of an organization with runs in progress  1  Lock all workspaces to ensure that no new runs will start before you change the name  1  Rename the organization  1  Update all components using the HCP Terraform API to the new organization name  This includes Terraform s  cloud  block CLI integration  the  tfe  Terraform provider  and any external API integrations  1  Unlock workspaces and resume normal operations        Plan   Billing  Review the organization s plan and any invoices for previous plan payments  Organization owners can also upgrade to one of HCP Terraform s paid plans  downgrade to a free plan  or begin a free trial of paid features        Tags  Click the   Tags   tab in the   Tags Management   screen to view single value tags that workspace managers added directly to their workspaces  For information about key value tag keys  refer to  Create and manage reserved tags   create and manage reserved tags    You can perform the following actions in the   Tags   tab   1  Search for a tag key or value  1  Click on a column header to sort tags        Teams       BEGIN  TFC only name pnp callout      include  tfc package callouts team management mdx       END  TFC only name pnp callout      All users in an organization can access the   Teams   page  which displays a list of  teams    within the organization    Organization owners and users with the  include secret teams permission   terraform cloud docs users teams organizations permissions include secret teams  can      view all  secret teams   terraform cloud docs users teams organizations teams manage team visibility      view each team s membership     manage team API tokens  HCP Terraform restricts team creation  team deletion  and management of team API tokens to organization owners and users with the  manage teams   terraform cloud docs users teams organizations permissions manage teams  permission  Organization owners and users with the  manage membership   terraform cloud docs users teams organizations permissions manage membership  permission can manage team membership  Remember that users must accept their organization invitations before you can add them to a team    permissions citation    intentionally unused   keep for maintainers       Users  Organization owners and users with  manage membership   terraform cloud docs users teams organizations permissions manage membership  permissions can invite HCP Terraform users into the organization  cancel invitations  and remove existing members   The list of users is separated into one tab for active users and one tab for invited users who have not yet accepted their invitations  For active users  the list includes usernames  email addresses  avatar icons  two factor authentication status  and current team memberships  Use the   Search by username or email   field to filter these lists   User invitations are always sent by email  you cannot invite someone using their HCP Terraform username  To invite a user to an organization   1  Click   Invite a user    The   invite a user   box appears  1  Enter the user s email address and optionally add them to one or more teams  If the user accepts the invitation  HCP Terraform automatically adds them to the specified teams   All permissions in HCP Terraform are managed through teams  Users can join an organization without belonging to any teams  but they cannot use Terraform Cloud features until they belong to a team  Refer to  permissions   terraform cloud docs users teams organizations permissions  for details    permissions citation    intentionally unused   keep for maintainers       Variable Sets  View all of the available variable sets and their variables  Users with   read and write variables  permissions   terraform cloud docs users teams organizations permissions general workspace permissions  can also create variable sets and assign them to one or more workspaces   Variable sets let you reuse the same variables across multiple workspaces in the organization  For example  you could define a variable set of provider credentials and automatically apply it to several workspaces  rather than manually defining credential variables in each  Changes to variable sets instantly apply to all appropriate workspaces  saving time and reducing errors from manual updates   Refer to the  variables overview   terraform cloud docs workspaces variables  documentation for details about variable types  scope  and precedence  Refer to  managing variables   terraform cloud docs workspaces variables managing variables  for details about how to create and manage variable sets        Health       BEGIN  TFC only name pnp callout      include  tfc package callouts health assessments mdx       END  TFC only name pnp callout      HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration  Health assessments include the following types of evaluations    Drift detection determines whether your real world infrastructure matches your Terraform configuration  Drift detection requires Terraform version 0 15 4     Continuous validation determines whether custom conditions in the workspace s configuration continue to pass after Terraform provisions the infrastructure  Continuous validation requires Terraform version 1 3 0    You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings  Refer to  Health   terraform cloud docs workspaces health  in the workspaces documentation for more details        Runs From the Workspaces page  click   Settings   in the sidebar  then   Runs   to view all of the current runs in your organization s workspaces  The   Runs   page displays    The name of the run   The run s ID   What triggered the run   The workspace and project where the run is taking place   When the latest change in the run occurred   A button allowing you to cancel that run  You can apply the following filters to limit the runs HCP Terraform displays    Click   Needs Attention   to display runs that require user input to continue  such as approving a plan or overriding a policy     Click   Running   to display runs that are in progress    Click   On Hold   to display paused runs    For precise filtering  click   More filters   and check the boxes to filter runs by specific  run statuses   terraform cloud docs run states    run operations   terraform cloud docs run modes and options   workspaces  or  agent pools   terraform cloud docs agents agent pools   Click   Apply filters   to list the runs that match your criteria   You can dismiss any of your filtering criteria by clicking the   X   next to the filter name above the table displaying your runs    For more details about run states  refer to  Run States and Stages   terraform cloud docs run states        Integrations       Cost Estimation  Enable and disable the  cost estimation   terraform cloud docs cost estimation  feature for all workspaces        Policies       BEGIN  TFC only name pnp callout      include  tfc package callouts policies mdx       END  TFC only name pnp callout      Policies let you define and enforce rules for Terraform runs  You can write them using either the  Sentinel   terraform cloud docs policy enforcement sentinel  or  Open Policy Agent  OPA    terraform cloud docs policy enforcement opa  policy as code frameworks and then group them into policy sets that you can apply to workspaces in your organization  To create policies and policy sets  you must have  permission to manage policies   terraform cloud docs users teams organizations permissions organization permissions         Policy Sets       BEGIN  TFC only name pnp callout      include  tfc package callouts policies mdx       END  TFC only name pnp callout      Create groups of policies and enforce those policy sets globally or on specific  projects   terraform cloud docs projects manage  and workspaces  You can create policy sets through the Terraform API  by connecting a VCS repository containing policies  or directly in HCP Terraform  To create policies and policy sets  you must have  permission to manage policies   terraform cloud docs users teams organizations permissions organization permissions    Refer to  Managing Policy Sets   terraform cloud docs policy enforcement manage policy sets  for details    permissions citation    intentionally unused   keep for maintainers       Run Tasks       BEGIN  TFC only name pnp callout      include  tfc package callouts run tasks mdx       END  TFC only name pnp callout      Manage the run tasks that you can add to workspaces within the organization   Run tasks   terraform cloud docs workspaces settings run tasks  let you integrate third party tools and services at specific stages in the HCP Terraform run lifecycle       Security       Agents       BEGIN  TFC only name pnp callout      include  tfc package callouts agents mdx       END  TFC only name pnp callout      Create and manage  HCP Terraform agent pools   terraform cloud docs agents   HCP Terraform agents let HCP Terraform communicate with isolated  private  or on premises infrastructure  This is useful for on premises infrastructure types such as vSphere  Nutanix  OpenStack  enterprise networking providers  and infrastructure within a protected enclave        API Tokens  Organization owners can set up a special  Organization API Token   terraform cloud docs users teams organizations api tokens  that is not associated with a specific user or team        Authentication  Organization owners can determine when users must reauthenticate and require  two factor authentication   terraform cloud docs users teams organizations 2fa  for all members of the organization        SSH Keys  Manage  SSH keys for cloning Git based modules   terraform cloud docs workspaces settings ssh keys  during Terraform runs  This does not include keys to access a connected VCS provider        SSO  Organization owners can set up an SSO provider for the organization       Version Control       VCS General  Configure  Automatically cancel plan only runs triggered by outdated commits   terraform cloud docs users teams organizations organizations vcs speculative plan management  to manage the setting        VCS Events       Note    This feature is in beta   Review the event logs for GitLab com connections        VCS Providers  Configure  VCS providers   terraform cloud docs vcs  to use in the organization  You must have  permission to manage VCS settings   terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers      Destruction and Deletion       Data Retention Policies   EnterpriseAlert  Data retention policies are exclusive to Terraform Enterprise  and not available in HCP Terraform   a href  https   developer hashicorp com terraform enterprise  Learn more about Terraform Enterprise  a     EnterpriseAlert   An organization owner can set or override the following data retention policies       Admin default policy       Do not auto delete       Auto delete data    Setting the data retention policy to   Admin default policy   disables the other data retention policy settings   By default  the   Do not auto delete   option is enabled for an organization  This option directs Terraform Enterprise to retain data associated with configuration and state versions  but organization owners can define configurable data retention policies that allow Terraform to  soft delete  the backing data associated with configuration versions and state versions  Soft deleting refers to marking a data object for garbage collection so that Terraform can delete the object after a set number of days   Once an object is soft deleted  any attempts to read the object will fail  Until the garbage collection process begins  you can restore soft deleted objects using the APIs described in the  configuration version documentation   terraform enterprise api docs configuration versions  and the  state version documentation   terraform enterprise api docs state versions   Terraform permanently deletes the archivist storage after the garbage collection grace period elapses   The organization policy is the default policy applied to all workspaces  but members of individual workspaces can set overriding policies for their workspaces that take precedence over the organization policy      Trial Expired Organizations  HCP Terraform paid features are available as a free trial  When a free trial has expired  the organization displays a banner reading   TRIAL EXPIRED   Upgrade Required     Organizations with expired trials return to the feature set of a free organization  but they retain any data created as part of paid features  Specifically  HCP Terraform disables the following features     Teams other than  owners  and locks users who do not belong to the  owners  team out of the organization  HCP Terraform preserves team membership and permissions and re enables them after you upgrade the organization    Sentinel policy checks  HCP Terraform preserves existing policies and policy sets and re enables them after you upgrade the organization    Cost estimation