Create and manage users

User accounts belong to individual people. Each user can be part of one or more teams, which are granted permissions on workspaces within an organization. A user can be a member of multiple organizations.

API

Use the Account API to get account details, update account information, and change your password.

Log in with a HashiCorp Cloud Platform account

We recommend using a HashiCorp Cloud Platform (HCP) 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 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 in your Account settings.

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. 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 or ask an organization owner to send you an invitation email to join their organization.

We recommend logging into HCP Terraform with your HCP account instead of creating a separate HCP Terraform account.

Joining organizations and teams

An organization owner or a user with Manage Membership permissions enabled must invite you to join their organization and add you to one or more teams.

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, 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 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 to display a user icon if you have associated one with your email address. Refer to the Gravatar documentation 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.

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.

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, 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.

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. 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.

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 for details.

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 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 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.

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 for details.

API tokens are required for the following tasks:

Authenticating with the HCP Terraform API. API calls require an Authorization: Bearer <TOKEN> HTTP header.
Authenticating with the HCP Terraform CLI integration or the remote backend. These require a token in the CLI configuration file or in the backend configuration.
Using private modules in command-line runs on local machines. This requires a token in the CLI configuration file.

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 for more details.

We recommend protecting your tokens by creating them with an expiration date and time. Refer to API Token Expiration for details.

Creating a token

To create a new token:

Click Create an API token. The Create API token box appears.
Enter a Description that explains what the token is for and click Create API token.
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.
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.

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.

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 and UI.
View available GitHub App installations with the HCP Terraform API 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