Transfer workspaces

You can use the Terraform Enterprise API to transfer workspaces from one organization to another within the same Terraform Enterprise instance. Refer to the Workspace transfers API reference for more information.

Introduction

When you transfer a workspace, Terraform Enterprise creates a new workspace in the destination organization and copies the following workspace data to the new workspace:

• Run history
• State history
• Workspace variables
• Workspace tags
• Policy set connections

Workflow

By default, Terraform Enterprise does not modify or remove the source workspace until you review and approve the migrated destination workspace. Once approved, Terraform Enterprise removes the source workspace and remaps the transferred workspace and related resource IDs so the destination workspace maintains its workspace ID and history.

To transfer a workspace from one organization to another, complete the following steps:

1. Ensure that the source workspace is unlocked.

2. Queue the transfer by sending a POST request to the /workspace-transfer API endpoint. Refer to Queue a transfer for more information.

3. Optionally, if you set the approval-mode property to required when you queued the transfer, send a POST request to the /workspace-transfers/:transfer_id/actions/resume endpoint to complete the transfer. Refer to Resume a transfer for more information.

4. Terraform Enterprise doesn't automatically recreate all configured integrations. After transferring a workspace, you should verify and reconfigure the following integrations:

   • VCS connections
   • SSH keys
   • Variable sets
   • Notification configuration
   • Run triggers
   • Agent pools
   • Run tasks
   • Team access

5. If the transfer fails, delete the workspace in the destination organization and unlock the workspace in the source organization.

Requirements

To transfer workspaces in Terraform Enterprise, you must meet the following requirements:

• You must either be a Terraform Enterprise administrator, or a member of the owners team in both the source and destination organization.
• You must authenticate all requests to these API endpoints with a user token.
• The source and destination organization must be different.
• The source workspace must not currently have a queued or active transfer.
• The source workspace must not be locked.
• The destination project must exist.
• The destination organization must not already contain a workspace with the same desired name.

Queue a transfer

POST /workspace-transfers

To transfer a workspace, first create a JSON file that configures how Terraform Enterprise transfers the workspace. Your JSON request body must include the following attributes:

• data.type: Must be "workspace-transfers".
• data.relationships.source-workspace.data.id: ID of the workspace to transfer.
• data.relationships.source-workspace.data.type: Must be "workspaces".
• data.relationships.destination-organization.data.id: ID of the organization to transfer the workspace to.
• data.relationships.destination-organization.data.type: Must be "organizations".
• data.relationships.destination-project.data.id: ID of the project in the destination organization to transfer the workspace to.
• data.relationships.destination-project.data.type: Must be "projects"

In the following example, the workspace with ID ws-abc123XYZ moves to the project prj-infra456 in the organization org-destABC.

{ 
  "data": { 
    "type": "workspace-transfers", 
    "attributes": { 
      "approval-mode": "required", 
      "cleanup-on-failure": false, 
      "history-cutoff": "2025-01-01T00:00:00.000Z", 
      "policy-set-mode": "skip", 
      "variable-mode": "copy", 
      "workspace-prefix": null, 
      "workspace-suffix": "-imported" 
    }, 
    "relationships": { 
      "source-workspace": { 
        "data": { "id": "ws-abc123XYZ", "type": "workspaces" } 
      }, 
      "destination-organization": { 
        "data": { "id": "org-destABC", "type": "organizations" } 
      }, 
      "destination-project": { 
        "data": { "id": "prj-infra456", "type": "projects" } 
      } 
    } 
  } 
} 

Next, make a POST request to the /workspace-transfer endpoint on a running Terraform Enterprise installation and include your JSON payload. The following example uses curl to queue the transfer, providing the JSON request body from a file named payload.json.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com/api/v2/workspace-transfers

Refer to the /workspace-transfers endpoint reference for details about request and response body attributes.

If you set approval-mode to required, Terraform Enterprise pauses the transfer after it copies the workspace to the new organization but before it deletes it from the source organization. To complete the transfer, you must manually resume the transfer. Refer to Resume a transfer for more information.

Resume a transfer

POST /workspace-transfers/:transfer_id/actions/resume

Terraform Enterprise pauses a transfer when you require approval when queueing the transfer or when it encounters an error that requires manual investigation. You cannot resume a canceled transfer.

To resume a paused transfer, send a POST request to the /workspace-transfers/:transfer_id/actions/resume endpoint. The following example uses curl to resume transfer wt-abcdefg12345678:

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://tfe.example.com/api/v2/workspace-transfers/wt-abcdefg12345678/actions/resume

Refer to the /workspace-transfers/:transfer_id/actions/resume endpoint reference for details about request and response body attributes.