> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# HCP Terraform

> Connect an HCP Terraform organization to review workspaces and recent run statuses, with workspace changes through your Approvals

Connect HCP Terraform so [CloudThinker](https://docs.cloudthinker.io/guide/agents/overview.md) can list your workspaces, report recent run statuses, and make approved workspace changes such as locking or renaming. The connection uses one organization name and that organization's API token.

## Prerequisites

* An HCP Terraform organization on app.terraform.io. Terraform Enterprise isn't supported.
* You, or someone helping you, must be an owner of that organization, because only owners can create or revoke the organization token.
* The **Admin** role in the CloudThinker workspace, which you need to add connections. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md).

> [!NOTE]
>
> An organization token has authority across the whole organization. CloudThinker limits itself to the actions on this page, but treat the token as an organization-wide secret.

## Setup

**1. Copy your organization name**

Sign in to [HCP Terraform](https://app.terraform.io/), select the organization, and copy its name exactly as shown, for example `platform-team`.

**2. Create the organization token**

Open **Organization settings → API Tokens → Organization Tokens**, set an expiration (the shortest your policy allows, and note the date), generate the token, and copy it right away. HCP Terraform shows it only once.

**3. Add the connection in CloudThinker**

Open **More → Workspace settings → Connections**, select **HCP Terraform**, enter the **Organization name** and **Organization token**, and click **Connect**. CloudThinker checks that the token belongs to that organization.

**Success state:** the connection shows a **Connected** status.

> [!WARNING]
>
> An organization has one organization token at a time. Generating a new one can break other automations that use the current token, so check with the organization owners first.

## Connection details

| Field | Description | Example |
| - | - | - |
| **Organization name** | The name shown in app.terraform.io. Not the URL or the HCP organization ID | `platform-team` |
| **Organization token** | From **Organization settings → API Tokens → Organization Tokens** | Hidden |

Each CloudThinker workspace holds one HCP Terraform connection, so it covers one organization. To cover a second organization, connect it in another CloudThinker workspace.

## Required permissions

Use the **organization token**, not a user or team token. HCP Terraform organization tokens can manage workspaces but can't start runs or upload configuration versions, which matches what this connection does.

> [!TIP]
>
> If another integration already uses the organization token, generating a new one breaks it. You can reuse the current token only if you can copy its value from your secret store, since HCP Terraform never shows it again. The trade-off: revoking it later breaks every integration that shares it.

## Agent capabilities

| Capability | What CloudThinker does | Approval |
| - | - | - |
| **Workspace inventory** | Lists workspaces with lock state, execution mode, auto-apply, and other settings. Reads the first 100 workspaces, in the order HCP Terraform's API returns them | No |
| **Recent run status** | Counts run statuses and lists recent runs. Reads the first 100 runs in the organization | No |
| **Workspace changes** | Creates, renames, locks, unlocks, or safely deletes a workspace | Yes |

CloudThinker states the scope it read in every answer. Changes address a workspace by name, so you can lock or rename one outside the first 100 by naming it. Run status describes Terraform runs, not the health of your infrastructure.

### What this connection can't do

It can't start plans, applies, or runs. It can't upload or download configuration or state, change variables, show sensitive outputs, force-unlock or force-delete a workspace, delete an organization, manage teams or tokens, or connect to Terraform Enterprise endpoints. Ask for a run and CloudThinker reports current run state, says it changed nothing, and stops.

### Verify the connection

```text theme={null}
List my HCP Terraform workspaces with their lock state and execution mode
```

Expect a table of workspaces with a line such as `Scope: first 100 workspaces`.

### Example prompts

```text theme={null}
Summarize recent HCP Terraform run statuses and list the runs that errored
Which HCP Terraform workspaces are locked right now?
Lock the HCP Terraform workspace named prod-network
```

## Write access

Before any workspace change, CloudThinker names the organization, workspace, action, and expected effect in the approval request. Asking for the change in your prompt doesn't count as approval.

Every change an agent makes goes through your workspace's [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On the default **Auto · Rules + AI · Ask me** mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace. Choose **Manual** to approve every change yourself.

HCP Terraform records each change under the organization token, not a person. A lock carries the reason `CloudThinker approved workspace lock`.

Safe delete uses HCP Terraform's own safe-delete action, which refuses a workspace that still manages resources. CloudThinker never force-deletes.

## Troubleshooting

> [accordion] "Invalid HCP Terraform organization name"
>
> Enter the name exactly as shown in HCP Terraform. Don't paste the organization URL or an HCP organization ID.

> [accordion] "HCP Terraform organization token is invalid or expired"
>
> Create a replacement organization token, update **Organization token**, and reconnect. Coordinate with the owners first, because the old token stops working.

> [accordion] "HCP Terraform organization was not found or the token cannot access it"
>
> **Organization name** and **Organization token** must come from the same organization. Fix whichever is wrong and reconnect.

> [accordion] "HCP Terraform token resolved a different organization"
>
> The token belongs to another organization. Enter that organization's name, or use the token from the organization you entered.

> [accordion] "HCP Terraform API rate limit reached. Retry later"
>
> Wait a few minutes, then reconnect once. Repeated retries keep you rate limited.

> [accordion] "HCP Terraform API is temporarily unavailable. Retry later"
>
> HCP Terraform couldn't complete the check. Retry later. CloudThinker doesn't treat this as a passing check.

> [accordion] Safe delete refused a workspace
>
> The workspace still manages resources. Remove that infrastructure through your normal Terraform workflow first, then ask again.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Track expiration.** Replace the token before the expiration date you set in setup.
- **Coordinate rotation.** Only one organization token is valid at a time. Confirm which integrations use it before you generate or revoke one.

## Related

> [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md)
>
> Control how CloudThinker asks before a workspace change.

> [card] [Pulumi connection](https://docs.cloudthinker.io/guide/connections/pulumi.md)
>
> Connect your other infrastructure-as-code service.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.