# Terraform cloud

SureCloud connects to Terraform Cloud (including Terraform Enterprise) to retrieve workspace configuration, policy check results, run history, and Sentinel or OPA policy compliance status. This allows SureCloud to verify that infrastructure changes are subject to policy checks before apply, that drift detection is configured, and that a reviewed and approved change process is being followed for infrastructure deployments.

## Authentication and setup

Terraform Cloud authenticates API requests using a team or user API token. SureCloud uses a read-only team token scoped to the relevant organisations.

{% stepper %}
{% step %}
**Create a read-only team in Terraform Cloud**

Log in to [app.terraform.io](https://app.terraform.io/) with an organisation owner account. Navigate to **Organisation Settings → Teams** and click **Create Team**. Name it `SureCloud CCM`. Under **Organisation Access**, grant **Read** access only. Click **Create Team**.
{% endstep %}

{% step %}
**Generate a team token**

From the team settings page, click **Create a team token**. Copy the token — it is only shown once.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Terraform Cloud → Connect**. Enter your Terraform Cloud organisation name and the team token. For Terraform Enterprise, also enter your instance URL (e.g. `https://terraform.yourcompany.com`). Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the team token securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **Terraform Cloud → Organisation Settings → Teams → SureCloud CCM** and update it in **SureCloud → Integrations → Terraform Cloud → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                      | Use Case                                                                                     |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `GET /api/v2/organizations/{org}/workspaces`  | Enumerate all workspaces including VCS connection and auto-apply settings                    |
| `GET /api/v2/workspaces/{id}/runs`            | Retrieve run history per workspace to evidence change management process                     |
| `GET /api/v2/runs/{id}/policy-checks`         | Retrieve Sentinel or OPA policy check results for a specific run                             |
| `GET /api/v2/organizations/{org}/policies`    | List configured Sentinel policies and their enforcement levels                               |
| `GET /api/v2/organizations/{org}/policy-sets` | Retrieve policy sets and their workspace scope assignments                                   |
| `GET /api/v2/workspaces/{id}`                 | Retrieve individual workspace detail including lock status and drift detection configuration |

## Pagination

`GET /api/v2/organizations/{org}/workspaces` and `GET /api/v2/workspaces/{id}/runs` use page-based pagination. SureCloud uses the `links.next` URL from each response to retrieve subsequent pages until no `next` link is present.

```json
GET /api/v2/organizations/{org}/workspaces?page[size]=100&page[number]=2
```

All list endpoints follow the same JSON:API pagination pattern.

## Required permissions

SureCloud requires a Terraform Cloud team token for a team with the following organisation-level access:

| Permission      | Purpose                                                     |
| --------------- | ----------------------------------------------------------- |
| Read workspaces | Enumerate workspaces and their configuration                |
| Read runs       | Access run history and policy check results                 |
| Read policies   | Read Sentinel/OPA policy definitions and enforcement levels |

No apply, plan-triggering, or variable write permissions are required.

## Polling frequency

| Data Type                             | Interval       |
| ------------------------------------- | -------------- |
| Workspace inventory and configuration | Every 24 hours |
| Run history and policy check results  | Every 6 hours  |
| Policy and policy set definitions     | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The team token is invalid or has been regenerated. Navigate to **Terraform Cloud → Organisation Settings → Teams → SureCloud CCM**, regenerate the token, and update it in **SureCloud → Integrations → Terraform Cloud → Edit Connection**.

</details>

<details>

<summary>Workspaces from some projects are missing</summary>

In Terraform Cloud's newer project-based model, workspaces are scoped to projects. The SureCloud CCM team must be granted access to each project. Navigate to **Organisation Settings → Projects** and add the SureCloud CCM team with read access to any projects whose workspaces are not appearing.

</details>

<details>

<summary>Policy check results are empty even though Sentinel policies are configured</summary>

Policy checks only appear on runs where policies are applied. Confirm that policy sets are assigned to the relevant workspaces in **Organisation Settings → Policy Sets**. If policies are configured but not assigned to any workspace, no policy check results will appear in run history.

</details>

<details>

<summary>Terraform Enterprise instance is unreachable</summary>

Confirm the Terraform Enterprise instance URL is correct and accessible from the SureCloud collector network. Self-hosted Terraform Enterprise instances on private networks may require a firewall rule. Contact SureCloud Support for guidance on connectivity requirements.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/terraform-cloud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.