In CI, prefer a host specific TF_TOKEN_ environment variable, fed from your secret manager, over a credentials block saved in a CLI config file. It keeps the token out of files on the runner and lets you scope it to one host. This feature needs Terraform 1.2.0 or later.
The two ways to supply a token
The CLI configuration file accepts a credentials block for each host, with a token value. If you work interactively, terraform login can write that file for you. The alternative is an environment variable named TF_TOKEN_ followed by the host name with periods turned into underscores. For example, TF_TOKEN_app_terraform_io supplies the bearer token for app.terraform.io.
Names with non ASCII characters must be converted to punycode with an ACE prefix first. Hyphens in host names can be encoded as double underscores. If several variables evaluate to the same host, Terraform picks the one defined last.
Why the environment variable suits pipelines
| Property | Config file | Environment variable |
|---|---|---|
| Token written to disk | Yes | Not by Terraform |
| Per host | Yes | Yes |
| Easy to inject from a secret store | Needs a file step | Direct |
| Visible in process listings or logs | Rarely | Possible if you print the environment |
The environment variable still needs care: do not echo the environment in debug steps, and restrict who can read job logs.
A credentials helper
Terraform also supports a credentials_helper block that points to a program for retrieving credentials. It is consulted only for hosts not set in a credentials block. Terraform does not ship any helpers, so you write or install your own.
Token type matters
For HCP Terraform and Terraform Enterprise, the token for command line use must be a user token or a team token. Organization tokens cannot be used for command line Terraform actions. Prefer a team token scoped to the workspaces a pipeline needs.
Steps
- Create a team token with the narrowest access that works.
- Store it in your CI secret store.
- Expose it only to the job that runs Terraform, as the correct
TF_TOKEN_variable. - Rotate it on a schedule and after any suspected exposure.
- Make sure the host name in your module sources and backend matches the credentials host, as the documentation requires.
Quick check
Does the variable name use dots?
No. Periods in the host name become underscores.
Can I use the same token for several hosts?
Each host has its own variable, so set one per host.
Are organization tokens fine for CLI runs?
Not for command line Terraform actions, according to the documentation.
Safeguard offers SBOM and dependency scanning and policy gates that can block a pull request on findings, and you can try a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
