Lab Solution Terraform Cloud API

Terraform Cloud’s REST API enables robust automation and integration for infrastructure provisioning. Teams can use it to:

API Workflow	Description
CI/CD Integration	Trigger Terraform runs from pipelines
State & Data Query	Programmatically retrieve Terraform state and outputs
Self-Service Portals	Build user-facing interfaces for provisioning
Custom CLI Automation	Enhance scripts with API-driven capabilities

In this lab you will:

Authenticate via the CLI
Configure workspace variables
Initiate a Terraform run using the API

The image shows a KodeKloud lab interface for Terraform Cloud API Driven Workflows, featuring a task description on the left and a Visual Studio Code editor on the right with instructions for opening a terminal and copying text.

1. Authenticate and Prepare

terraform login

Note

terraform login opens a browser for authentication and saves your token in ~/.terraform.d/credentials.tfrc.json.

Clone the sample repository and run the setup script:

git clone https://github.com/hashicorp/tfc-getting-started.git
cd tfc-getting-started
scripts/setup.sh

In the Terraform Cloud UI, navigate to User Settings → Tokens and create a new API token:

The image shows a dialog box titled "Create API token" with a field for a description and buttons to create the token or cancel.

Export your token and organization name as environment variables (replace MYORGNAME with your org):

export TOKEN=$(grep token ~/.terraform.d/credentials.tfrc.json | cut -d '"' -f4)
export ORG="MYORGNAME"

Warning

Keep your TOKEN secure. Do not commit it to source control or share it publicly.

2. Retrieve the Workspace ID

Every Terraform Cloud workspace has a unique ID. Store it in an environment variable:

export WORKSPACE_ID=$(
  curl -s \
    --header "Authorization: Bearer $TOKEN" \
    https://app.terraform.io/api/v2/organizations/$ORG/workspaces/$WORKSPACE_NAME \
  | jq -r '.data.id'
)

You can also copy the workspace ID from the Terraform Cloud UI under your workspace name:

The image shows a Terraform Cloud workspace overview for "devops-aws-hashicat-dev," displaying details of the latest run, including resources, Terraform version, and run status.

Validate that your environment variables are set correctly:

printenv | grep -E 'TOKEN|ORG|WORKSPACE_ID'

3. Define Variable Payloads

Create three JSON payloads in the json/ directory to configure workspace variables:

File	Key	Value	Category	Sensitive	HCL
`placeholder.json`	placeholder	placedog.net	terraform	false	false
`width.json`	width	800	terraform	false	false
`height.json`	height	600	terraform	false	false

// json/placeholder.json
{
  "data": {
    "type": "vars",
    "attributes": {
      "key": "placeholder",
      "value": "placedog.net",
      "category": "terraform",
      "hcl": false
    }
  }
}

// json/width.json
{
  "data": {
    "type": "vars",
    "attributes": {
      "key": "width",
      "value": "800",
      "category": "terraform",
      "hcl": false,
      "sensitive": false
    }
  }
}

// json/height.json
{
  "data": {
    "type": "vars",
    "attributes": {
      "key": "height",
      "value": "600",
      "category": "terraform",
      "hcl": false
    }
  }
}

Refer to the Workspace Variables API documentation for details on the POST /workspaces/:id/vars endpoint:

The image shows a section of the Terraform documentation, specifically detailing how to create a variable using a POST request in the Workspace Variables API. It includes parameters, descriptions, and a request body structure.

4. Create Workspace Variables via API

Switch into the JSON directory and run the following curl commands:

cd tfc-getting-started/json

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @placeholder.json \
  https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/vars | jq

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @width.json \
  https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/vars | jq

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @height.json \
  https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/vars | jq

Refresh the Variables page in the Terraform Cloud UI to confirm the new variables:

The image shows a Terraform Cloud interface displaying workspace variables, including keys like "height" and "width" with their respective values and categories. The sidebar includes navigation options such as Workspaces, Overview, Runs, States, Variables, and Settings.

5. Trigger a Terraform Run via API

Prepare the apply.json payload to create a run:

// apply.json
{
  "data": {
    "attributes": {
      "is-destroy": false,
      "message": "Terraform Cloud API is Magic!"
    },
    "type": "runs",
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "REPLACEME"
        }
      }
    }
  }
}

Replace REPLACEME with your $WORKSPACE_ID:

sed -i "s/REPLACEME/$WORKSPACE_ID/" apply.json

Note

On macOS, use sed -i '' for inline replacements.

Using the Runs API documentation, execute:

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @apply.json \
  https://app.terraform.io/api/v2/runs | jq

Monitor the run status (pending, planned, applied) in the Terraform Cloud UI:

The image shows a Terraform Cloud interface with a run triggered, displaying the status of a plan and cost estimation, and an "Apply pending" section with a comment box for confirmation.

Conclusion

You have successfully:

Authenticated to Terraform Cloud via CLI
Used the Workspace Variables API to set variables
Triggered a Terraform run through the Runs API

Next steps: explore additional API endpoints for run cancellation, policy checks, cost estimation, and more.