Getting Connected and Authenticated with HCP Terraform

Earlier we introduced what HCP Terraform is and why teams use it. If you already have a free HCP Terraform account, you can continue. Right now your local Terraform CLI and your HCP Terraform account are separate and unaware of each other. This guide shows how to connect your local Terraform to HCP Terraform and authenticate so they can communicate securely. By the end you’ll understand the two pieces involved and how they work together:

Tell Terraform where to connect (the cloud block in your Terraform configuration).
Prove your identity to HCP Terraform (an API token produced via terraform login or an environment variable for non-interactive usage).

Overview

Configure the cloud block in your root terraform settings so Terraform targets HCP Terraform.
Authenticate using terraform login (interactive) or the environment variable TF_TOKEN_app_terraform_io (non-interactive/CI).

Step 1 — Add the cloud block to your configuration Add the cloud block inside your root terraform settings block (the same place you declare required_providers and required_version). This tells Terraform to use HCP Terraform (Terraform Cloud) instead of a local-only workflow.

terraform {
  cloud {
    organization = "my-org"
    hostname     = "app.terraform.io"

    workspaces {
      project = "networking-development"

      tags = {
        layer  = "networking"
        source = "cli"
      }
    }
  }
}

Key points:

organization must exactly match the organization name in your HCP Terraform account; otherwise Terraform cannot locate it.
hostname = "app.terraform.io" is the default for HCP Terraform and can be omitted unless you’re using a custom host (for example, Terraform Enterprise).
The workspaces block determines which workspace(s) to target:
- Use name to target a specific workspace name.
- Use prefix to target workspaces whose names share a common prefix.
- Use tags to match by tags. If tags match multiple workspaces, Terraform will prompt you to choose one at runtime.
- Some organizations support a project attribute — include it only if your organization and CLI support it.

A note about backends:

The cloud block is the modern mechanism for connecting to HCP Terraform.
It is mutually exclusive with a backend block (for example, S3, Azure Blob). You cannot have both in the same configuration. If you include both, Terraform will return an error.

Use the cloud block to connect to HCP Terraform. Do not combine a cloud block and a backend block in the same configuration—choose one or the other.

Step 2 — Authenticate with terraform login After configuring the cloud block, authenticate so HCP Terraform trusts your CLI. Interactive login (recommended for local development)

$ terraform login

When you run terraform login, Terraform describes what will happen and where it will store the token. A typical interactive session:

$ terraform login
Terraform will request an API token for app.terraform.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
/Users/bk/.terraform.d/credentials.tfrc.json

Do you want to proceed?
Only 'yes' will be accepted to confirm.

Enter a value: yes

Terraform opens your default browser and takes you to the HCP Terraform token generation page. In the browser you can give the token a description (for example, “Terraform login”) and optionally set an expiration. Once you click “Generate Token”, HCP Terraform displays the token only once — copy it immediately. After copying the token, return to your terminal and paste it when prompted. Terraform saves that token in the credentials file shown above.

Terraform stores the API token in plain text at ~/.terraform.d/credentials.tfrc.json. Ensure the file has appropriate permissions so unauthorized users cannot read it.

What the credentials file looks like Terraform writes a JSON structure mapping hostnames to tokens. Example:

{
  "credentials": {
    "app.terraform.io": {
      "token": "FCApkzYtVEW0xg.atlasv1.4clxpkbzVvHqgebEhAPeiVhCMyuU1kUF09ONao4t0Ubo4uMv3gDEsgy9JYHBExsLwEw"
    }
  }
}

Once stored, subsequent runs of terraform init, terraform plan, terraform apply, etc., will use that token automatically. After a successful login you will see a confirmation in your terminal and can continue using Terraform against your HCP Terraform account. Token types in HCP Terraform HCP Terraform supports several token types with different scopes and uses. The following table summarizes typical token types and their intended uses:

Token type	Typical use case	Notes
Organization token	Administrative tasks (teams, membership, workspaces)	Cannot run plans/applies; for org-level management
Team token	Automation (CI/CD)	Can run plan/apply operations; commonly stored as pipeline secrets
User token	Interactive CLI (`terraform login`)	Carries permissions of the creating user; can access multiple orgs that the user belongs to
Audit token	Read-only access to audit/monitoring APIs	Intended for compliance and observation; cannot run Terraform operations

An infographic titled "HCP Terraform - API Token Types" showing four token categories—Organization, Team, User, and Audit Tokens—each with an icon and brief bullet-point descriptions. It summarizes the use cases and permission levels for each token type.

Remember: terraform login generates a user token. Non-interactive authentication (CI/CD) For automation that cannot use an interactive browser (CI pipelines, containers, headless servers), set an environment variable with a valid token. Example:

export TF_TOKEN_app_terraform_io="FCApkzYtVEW0xg.atlasv1.4clxpkbzVvHqgebEhAPeiVhCMyuU1kUF09ONao4t0Ubo4uMv3gDEsgy9JYHBExsLwEw"

Place that environment variable in your CI/CD secret manager (GitHub Actions secrets, Jenkins credentials, etc.) so pipeline jobs can authenticate non-interactively. Use team tokens or automation-specific user tokens with least privilege appropriate for the job. Recap

Add a cloud block to your Terraform settings to direct Terraform to HCP Terraform (Terraform Cloud).
Authenticate with terraform login for interactive use or with TF_TOKEN_app_terraform_io for non-interactive automation.
Choose token types carefully: user tokens for developers, team tokens for CI, org tokens for administrative tasks, and audit tokens for monitoring.
Keep API tokens secure. The local credentials file is plain text — enforce file permissions and store tokens in a secrets manager for automation.

Links and references

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Getting Connected and Authenticated with HCP Terraform

Watch Video