How-to delete a workspace from Terraform Cloud or Terraform Enterprise

Introduction

This guide explains how to remove an unwanted workspace from an organization in HCP Terraform or Terraform Enterprise.

Note: Deleting a workspace is an irreversible action. All variables, settings, alert history, run history, and state files associated with the workspace will be permanently removed. This action does not destroy the infrastructure managed by the workspace. If you need to destroy the infrastructure, you must do so before deleting the workspace.

Prerequisites

• You must have Manage Workspaces permissions for the organization containing the workspace.

Procedure

You can delete a workspace using two methods: the user interface (UI) or the API.

Method 1: Using the User Interface (UI)

1. Log in to the HCP Terraform UI or your Terraform Enterprise instance at https://<TFE_HOSTNAME>/app.
2. Select the organization that contains the workspace you want to delete.
3. Select the target workspace.
4. Navigate to Settings > Destruction and Deletion.
5. Follow the on-screen instructions to confirm and complete the deletion process.

Method 2: Using the API

1. Use the DELETE /organizations/:organization_name/workspaces/:workspace_name endpoint to remove a workspace. Refer to the Delete a Workspace API documentation for detailed instructions.

   The following example shows a sample API request to delete a workspace.

   $ curl \
     --header "Authorization: Bearer $TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     --request DELETE \
     https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1

Verification

After performing the deletion, you can verify that the workspace has been removed by checking the UI or by using the List Workspaces API endpoint.

The following example shows a sample API request to list all workspaces in an organization.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/workspaces