Terraform
Workspaces API
Workspaces represent running infrastructure managed by Terraform.
Viewing a workspace (individually or in a list) requires permission to read runs. Changing settings and force-unlocking require admin access to the workspace. Locking and unlocking a workspace requires permission to lock and unlock the workspace. (More about permissions.)
Create a Workspace
POST /organizations/:organization_name/workspaces
Parameter | Description |
---|---|
:organization_name | The name of the organization to create the workspace in. The organization must already exist in the system, and the user must have permissions to create new workspaces. |
Note: Workspace creation is restricted to the owners team, teams with the "Manage all workspaces" permission, teams with the "Manage all projects" permission, and the organization API token.
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
By supplying the necessary attributes under a vcs-repository
object, you can create a workspace that is configured against a VCS Repository.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "workspaces" . | |
data.attributes.name | string | The name of the workspace, which can only include letters, numbers, - , and _ . This will be used as an identifier and must be unique in the organization. | |
data.attributes.agent-pool-id | string | (nothing) | Required when execution-mode is set to agent . The ID of the agent pool belonging to the workspace's organization. This value must not be specified if execution-mode is set to remote or local or if operations is set to true . |
data.attributes.allow-destroy-plan | boolean | true | Whether destroy plans can be queued on the workspace. |
data.attributes.assessments-enabled | boolean | false | (previously drift-detection ) Whether or not HCP Terraform performs health assessments for the workspace. May be overriden by the organization setting assessments-enforced . Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in Remote execution mode. |
data.attributes.auto-apply | boolean | false | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, with some exceptions. |
data.attributes.auto-apply-run-trigger | boolean | false | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers. |
data.attributes.auto-destroy-at | string | (nothing) | Timestamp when the next scheduled destroy run will occur, refer to Scheduled Destroy. |
data.attributes.auto-destroy-activity-duration | string | (nothing) | Value and units for automatically scheduled destroy runs based on workspace activity. Valid values are greater than 0 and four digits or less. Valid units are d and h . For example, to queue destroy runs after fourteen days of inactivity set auto-destroy-activity-duration: "14d" . |
data.attributes.description | string | (nothing) | A description for the workspace. |
data.attributes.execution-mode | string | (nothing) | Which execution mode to use. Valid values are remote , local , and agent . When set to local , the workspace will be used for state storage only. This value must not be specified if operations is specified, and must be specified if setting-overwrites.execution-mode is set to true . |
data.attributes.file-triggers-enabled | boolean | true | Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either trigger-prefixes in conjunction with working_directory or trigger-patterns to describe the set of changed files that will start a run. If disabled, any push will trigger a run. |
data.attributes.global-remote-state | boolean | false | Whether the workspace should allow all workspaces in the organization to access its state data during runs. If false , then only specifically approved workspaces can access its state. Manage allowed workspaces using the Remote State Consumers endpoints, documented later on this page. Note: Terraform Enterprise admins can choose the default value for new workspaces if this attribute is omitted. |
data.attributes.operations | boolean | true | DEPRECATED Use execution-mode instead. Whether to use remote execution mode. When set to false , the workspace will be used for state storage only. This value must not be specified if execution-mode is specified. |
data.attributes.queue-all-runs | boolean | false | Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued. |
data.attributes.source-name | string | (nothing) | A friendly name for the application or client creating this workspace. If set, this will be displayed on the workspace as "Created via <SOURCE NAME> ". |
data.attributes.source-url | string | (nothing) | A URL for the application or client creating this workspace. This can be the URL of a related resource in another app, or a link to documentation or other info about the client. |
data.attributes.speculative-enabled | boolean | true | Whether this workspace allows automatic speculative plans. Setting this to false prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API. |
data.attributes.terraform-version | string | (special) | The version of Terraform to use for this workspace. This can be either an exact version or a version constraint (like ~> 1.0.0 ); if you specify a constraint, the workspace will always use the newest release that meets that constraint. If omitted when creating a workspace, this defaults to the latest released version. |
data.attributes.trigger-patterns | array | [] | List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository. |
data.attributes.trigger-prefixes | array | [] | List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform will start a run when files are changed in any directory path matching the provided set of prefixes. |
data.attributes.vcs-repo.branch | string | (nothing) | The repository branch that Terraform will execute from. If omitted or submitted as an empty string, this defaults to the repository's default branch (e.g. master ) . |
data.attributes.vcs-repo.identifier | string | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is :org/:project/_git/:repo . | |
data.attributes.vcs-repo.ingress-submodules | boolean | false | Whether submodules should be fetched when cloning the VCS repository. |
data.attributes.vcs-repo.oauth-token-id | string | The VCS Connection (OAuth Connection + Token) to use. This ID can be obtained from the oauth-tokens endpoint. | |
data.attributes.vcs-repo.tags-regex | string | (nothing) | A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. |
data.attributes.vcs-repo | object | (nothing) | Settings for the workspace's VCS repository. If omitted, the workspace is created without a VCS repo. If included, you must specify at least the oauth-token-id and identifier keys below. |
data.attributes.working-directory | string | (nothing) | A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository. |
data.attributes.setting-overwrites | object | The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is true by default. To overwrite the default inherited value, set an attribute's value to false . For example, to set execution-mode as the organization default, you set setting-overwrites.execution-mode = false . | |
data.relationships.project.data.id | string | The ID of the project to create the workspace in. If left blank, the workspace will be created in the organization's default project. You must have permission to create workspaces in the project, either by organization-level permissions or team admin access to a specific project. |
Sample Payload
Without a VCS repository
{
"data": {
"attributes": {
"name": "workspace-1",
},
"type": "workspaces"
}
}
With a VCS repository
{
"data": {
"attributes": {
"name": "workspace-2",
"terraform_version": "0.11.1",
"working-directory": "",
"vcs-repo": {
"identifier": "example/terraform-test-proj",
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"branch": "",
"tags-regex": null
}
},
"type": "workspaces"
}
}
Using Git Tags
HCP Terraform triggers a run when you push a Git tag that matches the regular expression (SemVer): 1.2.3
, 22.33.44
, etc.
{
"data": {
"attributes": {
"name": "workspace-3",
"terraform_version": "0.12.1",
"file-triggers-enabled": false,
"working-directory": "/networking",
"vcs-repo": {
"identifier": "example/terraform-test-proj-monorepo",
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"branch": "",
"tags-regex": "\d+.\d+.\d+"
}
},
"type": "workspaces"
}
}
For a monorepo using trigger prefixes
A run will be triggered in this workspace when changes are detected in any of the specified directories: /networking
, /modules
, or /vendor
.
{
"data": {
"attributes": {
"name": "workspace-3",
"terraform_version": "0.12.1",
"file-triggers-enabled": true,
"trigger-prefixes": ["/modules", "/vendor"],
"working-directory": "/networking",
"vcs-repo": {
"identifier": "example/terraform-test-proj-monorepo",
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"branch": ""
},
"updated-at": "2017-11-29T19:18:09.976Z"
},
"type": "workspaces"
}
}
For a monorepo using trigger patterns
A run will be triggered in this workspace when HCP Terraform detects any of the following changes:
- A file with the extension
tf
in any directory structure in which the last folder is namednetworking
(e.g.,root/networking
androot/module/networking
) - Any file changed in the folder
/base
, no subfolders are included - Any file changed in the folder
/submodule
and all of its subfolders
{
"data": {
"attributes": {
"name": "workspace-4",
"terraform_version": "1.2.2",
"file-triggers-enabled": true,
"trigger-patterns": ["/**/networking/*.tf", "/base/*", "/submodule/**/*"],
"vcs-repo": {
"identifier": "example/terraform-test-proj-monorepo",
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"branch": ""
},
"updated-at": "2022-06-09T19:18:09.976Z"
},
"type": "workspaces"
}
}
Using HCP Terraform agents
HCP Terraform agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure.
{
"data": {
"attributes": {
"name":"workspace-1",
"execution-mode": "agent",
"agent-pool-id": "apool-ZjT6A7mVFm5WHT5a"
}
},
"type": "workspaces"
}
Using an organization default execution mode
{
"data": {
"attributes": {
"name":"workspace-with-default",
"setting-overwrites": {
"execution-mode": false
}
}
},
"type": "workspaces"
}
With a project
{
"data": {
"type": "workspaces",
"attributes": {
"name": "workspace-in-project"
},
"relationships": {
"project": {
"data": {
"type": "projects",
"id": "prj-jT92VLSFpv8FwKtc"
}
}
}
}
}
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/organizations/my-organization/workspaces
Sample Response
With a VCS repository
{
"data": {
"id": "ws-KTuq99JSzgmDSvYj",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"apply-duration-average": null,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-activity-duration": null,
"created-at": "2021-08-16T21:50:58.726Z",
"description": null,
"environment": "default",
"execution-mode": "remote",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:50:58.726Z",
"locked": false,
"locked-reason": "",
"name": "workspace-2",
"oauth-client-name": "github example",
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"display-identifier": "example/terraform-test-proj",
"identifier": "example/terraform-test-proj",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"repository-http-url": "https://github.com/example/terraform-test-proj",
"service-provider": "github",
"tags-regex": null,
"webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"
},
"vcs-repo-identifier": "example/terraform-test-proj",
"working-directory": "",
"workspace-kpis-runs-count": null,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2",
"self-html": "/app/my-organization/workspaces/workspace-2"
},
"relationships": {
"relationships": {
"agent-pool": {
"data": null
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Without a VCS repository
{
"data": {
"id": "ws-6jrRyVDv1J8zQMB5",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-status": null,
"auto-destroy-activity-duration": null,
"inherits-project-auto-destroy": null,
"created-at": "2021-08-16T21:22:49.566Z",
"description": null,
"environment": "default",
"execution-mode": "agent",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:22:49.566Z",
"last-assessment-result-at" : "2021-08-17T21:20:12.908Z",
"locked": true,
"locked-reason": null,
"name": "workspace-1",
"oauth-client-name": null,
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"updated-at": "2021-08-16T21:22:49.566Z",
"vcs-repo": null,
"vcs-repo-identifier": null,
"working-directory": null,
"workspace-kpis-runs-count": 8,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1",
"self-html": "/app/my-organization/workspaces/workspace-1"
},
"relationships": {
"agent-pool": {
"data": {
"id": "apool-QxGd2tRjympfMvQc",
"type": "agent-pools"
}
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
},
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Update a Workspace
A workspace can be updated via two endpoints, which behave identically. One refers to a workspace by its ID, and the other by its name and organization.
PATCH /workspaces/:workspace_id
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace to update |
PATCH /organizations/:organization_name/workspaces/:name
Parameter | Description |
---|---|
:organization_name | The name of the organization the workspace belongs to. |
:name | The name of the workspace to update, which can only include letters, numbers, - , and _ . This will be used as an identifier and must be unique in the organization. |
Request Body
These PATCH endpoints require a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "workspaces" . | |
data.attributes.name | string | (previous value) | A new name for the workspace, which can only include letters, numbers, - , and _ . This will be used as an identifier and must be unique in the organization. Warning: Changing a workspace's name changes its URL in the API and UI. |
data.attributes.agent-pool-id | string | (previous value) | Required when execution-mode is set to agent . The ID of the agent pool belonging to the workspace's organization. This value must not be specified if execution-mode is set to remote or local or if operations is set to true . |
data.attributes.allow-destroy-plan | boolean | (previous value) | Whether destroy plans can be queued on the workspace. |
data.attributes.assessments-enabled | boolean | false | (previously drift-detection ) Whether or not HCP Terraform performs health assessments for the workspace. May be overriden by the organization setting assessments-enforced . Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in Remote execution mode. |
data.attributes.auto-apply | boolean | (previous value) | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, with some exceptions. |
data.attributes.auto-apply-run-trigger | boolean | (previous value) | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers. |
data.attributes.auto-destroy-at | string | (previous value) | Timestamp when the next scheduled destroy run will occur, refer to Scheduled Destroy. |
data.attributes.auto-destroy-activity-duration | string | (previous value) | Value and units for automatically scheduled destroy runs based on workspace activity. Valid values are greater than 0 and four digits or less. Valid units are d and h . For example, to queue destroy runs after fourteen days of inactivity set auto-destroy-activity-duration: "14d" . |
data.attributes.description | string | (previous value) | A description for the workspace. |
data.attributes.execution-mode | string | (previous value) | Which execution mode to use. Valid values are remote , local , and agent . When set to local , the workspace will be used for state storage only. This value must not be specified if operations is specified, and must be specified if setting-overwrites.execution-mode is set to true . |
data.attributes.file-triggers-enabled | boolean | (previous value) | Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either trigger-prefixes in conjunction with working_directory or trigger-patterns to describe the set of changed files that will start a run. If disabled, any push will trigger a run. |
data.attributes.global-remote-state | boolean | (previous value) | Whether the workspace should allow all workspaces in the organization to access its state data during runs. If false , then only specifically approved workspaces can access its state. Manage allowed workspaces using the Remote State Consumers endpoints, documented later on this page. |
data.attributes.operations | boolean | (previous value) | DEPRECATED Use execution-mode instead. Whether to use remote execution mode. When set to false , the workspace will be used for state storage only. This value must not be specified if execution-mode is specified. |
data.attributes.queue-all-runs | boolean | (previous value) | Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued. |
data.attributes.speculative-enabled | boolean | (previous value) | Whether this workspace allows automatic speculative plans. Setting this to false prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API. |
data.attributes.terraform-version | string | (previous value) | The version of Terraform to use for this workspace. This can be either an exact version or a version constraint (like ~> 1.0.0 ); if you specify a constraint, the workspace will always use the newest release that meets that constraint. |
data.attributes.trigger-patterns | array | (previous value) | List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository. |
data.attributes.trigger-prefixes | array | (previous value) | List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform will start a run when files are changed in any directory path matching the provided set of prefixes. |
data.attributes.vcs-repo.branch | string | (previous value) | The repository branch that Terraform will execute from. |
data.attributes.vcs-repo.identifier | string | (previous value) | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is :org/:project/_git/:repo . |
data.attributes.vcs-repo.ingress-submodules | boolean | (previous value) | Whether submodules should be fetched when cloning the VCS repository. |
data.attributes.vcs-repo.oauth-token-id | string | The VCS Connection (OAuth Connection + Token) to use as identified. Get this ID from the oauth-tokens endpoint. You can not specify this value if github-app-installation-id is specified. | |
data.attributes.vcs-repo.github-app-installation-id | string | The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from Account Settings within HCP Terraform. You can not specify this value if oauth-token-id is specified. | |
data.attributes.vcs-repo.tags-regex | string | (previous value) | A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. |
data.attributes.vcs-repo | object or null | (previous value) | To delete a workspace's existing VCS repo, specify null instead of an object. To modify a workspace's existing VCS repo, include whichever of the keys below you wish to modify. To add a new VCS repo to a workspace that didn't previously have one, include at least the oauth-token-id and identifier keys. |
data.attributes.working-directory | string | (previous value) | A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository. |
data.attributes.setting-overwrites | object | The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is true by default. To overwrite the default inherited value, set an attribute's value to false . For example, to set execution-mode as the organization default, you set setting-overwrites.execution-mode = false . | |
data.relationships.project.data.id | string | (previous value) | The ID of the project to move the workspace to. If left blank or unchanged, the workspace will not be moved. You must have admin permissions on both the source project and destination project in order to move a workspace between projects. |
Sample Payload
{
"data": {
"attributes": {
"name": "workspace-2",
"resource-count": 0,
"terraform_version": "0.11.1",
"working-directory": "",
"vcs-repo": {
"identifier": "example/terraform-test-proj",
"branch": "",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ"
},
"updated-at": "2017-11-29T19:18:09.976Z"
},
"relationships": {
"project": {
"data": {
"type": "projects",
"id": "prj-7HWWPGY3fYxztELU"
}
}
},
"type": "workspaces"
}
}
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-2
Sample Response
{
"data": {
"id": "ws-KTuq99JSzgmDSvYj",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"apply-duration-average": null,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-activity-duration": null,
"created-at": "2021-08-16T21:50:58.726Z",
"description": null,
"environment": "default",
"execution-mode": "remote",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:50:58.726Z",
"locked": false,
"locked-reason": "",
"name": "workspace-2",
"oauth-client-name": "github example",
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"display-identifier": "example/terraform-test-proj",
"identifier": "example/terraform-test-proj",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"repository-http-url": "https://github.com/example/terraform-test-proj",
"service-provider": "github",
"tags-regex": null,
"webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"
},
"vcs-repo-identifier": "example/terraform-test-proj",
"working-directory": "",
"workspace-kpis-runs-count": null,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2",
"self-html": "/app/my-organization/workspaces/workspace-2"
},
"relationships": {
"relationships": {
"agent-pool": {
"data": null
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
List workspaces
This endpoint lists workspaces in the organization.
GET /organizations/:organization_name/workspaces
Parameter | Description |
---|---|
:organization_name | The name of the organization to list the workspaces of. |
Query Parameters
This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [
as %5B
and ]
as %5D
if your tooling doesn't automatically encode URLs.
Parameter | Description |
---|---|
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 workspaces per page. |
search[name] | Optional. If specified, restricts results to workspaces with a name that matches the search string using a fuzzy search. |
search[tags] | Optional. If specified, restricts results to workspaces with that tag. If multiple comma separated values are specified, results matching all of the tags are returned. |
search[exclude-tags] | Optional. If specified, results exclude workspaces with that tag. If multiple comma separated values are specified, workspaces with tags matching any of the tags are excluded. |
search[wildcard-name] | Optional. If specified, restricts results to workspaces with partial matching, using * on prefix, suffix, or both. For example, search[wildcard-name]=*-prod returns all workspaces ending in -prod , search[wildcard-name]=prod-* returns all workspaces beginning with prod- , and search[wildcard-name]=*-prod-* returns all workspaces with substring -prod- regardless of prefix and/or suffix. |
sort | Optional. Allows sorting the organization's workspaces by a provided value. You can sort by "name" , "current-run.created-at" (the time of the current run), and "latest-change-at" (the creation time of the latest state version or the workspace itself if no state version exists). Prepending a hyphen to the sort parameter reverses the order. For example, "-name" sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable. |
filter[project][id] | Optional. If specified, restricts results to workspaces in the specific project. |
filter[current-run][status] | Optional. If specified, restricts results to workspaces that match the status of a current run. |
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/organizations/my-organization/workspaces
Sample Response
{
"data": [
{
"id": "ws-6jrRyVDv1J8zQMB5",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-status": null,
"auto-destroy-activity-duration": null,
"inherits-project-auto-destroy": null,
"created-at": "2021-08-16T21:22:49.566Z",
"description": null,
"environment": "default",
"execution-mode": "agent",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:22:49.566Z",
"last-assessment-result-at" : "2021-08-17T21:20:12.908Z",
"locked": true,
"locked-reason": null,
"name": "workspace-1",
"oauth-client-name": null,
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"updated-at": "2021-08-16T21:22:49.566Z",
"vcs-repo": null,
"vcs-repo-identifier": null,
"working-directory": null,
"workspace-kpis-runs-count": 8,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1",
"self-html": "/app/my-organization/workspaces/workspace-1"
},
"relationships": {
"agent-pool": {
"data": {
"id": "apool-QxGd2tRjympfMvQc",
"type": "agent-pools"
}
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
},
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
},
],
"links": {
"first": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"last": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"next": null,
"prev": null,
"self": "https://app.terraform.io/api/v2/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20"
},
"meta": {
"pagination": {
"current-page": 1,
"next-page": null,
"page-size": 20,
"prev-page": null,
"total-count": 1,
"total-pages": 1
}
}
}
Show workspace
Details on a workspace can be retrieved from two endpoints, which behave identically.
One refers to a workspace by its ID:
GET /workspaces/:workspace_id
Parameter | Description |
---|---|
:workspace_id | The workspace ID |
The other refers to a workspace by its name and organization:
GET /organizations/:organization_name/workspaces/:name
Parameter | Description |
---|---|
:organization_name | The name of the organization the workspace belongs to. |
:name | The name of the workspace to show details for, which can only include letters, numbers, - , and _ . |
Workspace performance attributes
The following attributes are helpful in determining the overall health and performance of your workspace configuration. These metrics refer to the past 30 runs that have either resulted in an error or successfully applied.
Parameter | Type | Description |
---|---|---|
data.attributes.apply-duration-average | number | This is the average time runs spend in the apply phase, represented in milliseconds |
data.attributes.plan-duration-average | number | This is the average time runs spend in the plan phase, represented in milliseconds |
data.attributes.policy-check-failures | number | Reports the number of run failures resulting from a policy check failure |
data.attributes.run-failures | number | Reports the number of failed runs |
data.attributes.workspace-kpis-run-count | number | Total number of runs taken into account by these metrics |
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1
Sample Response
{
"data": {
"id": "ws-6jrRyVDv1J8zQMB5",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-status": null,
"auto-destroy-activity-duration": null,
"inherits-project-auto-destroy": null,
"created-at": "2021-08-16T21:22:49.566Z",
"description": null,
"environment": "default",
"execution-mode": "agent",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:22:49.566Z",
"last-assessment-result-at" : "2021-08-17T21:20:12.908Z",
"locked": true,
"locked-reason": null,
"name": "workspace-1",
"oauth-client-name": null,
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"updated-at": "2021-08-16T21:22:49.566Z",
"vcs-repo": null,
"vcs-repo-identifier": null,
"working-directory": null,
"workspace-kpis-runs-count": 8,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1",
"self-html": "/app/my-organization/workspaces/workspace-1"
},
"relationships": {
"agent-pool": {
"data": {
"id": "apool-QxGd2tRjympfMvQc",
"type": "agent-pools"
}
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
},
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Safe Delete a workspace
When you delete an HCP Terraform workspace with resources, Terraform can no longer track or manage that infrastructure. During a safe delete, HCP Terraform only deletes the workspace if it is not managing resources.
You can safe delete a workspace using two endpoints that behave identically. The first endpoint identifies a workspace with the workspace ID, and the other identifies the workspace by its name and organization.
POST /workspaces/:workspace_id/actions/safe-delete
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace to delete. |
POST /organizations/:organization_name/workspaces/:name/actions/safe-delete
Parameter | Description |
---|---|
:organization_name | The name of the workspace's organization. |
:name | The name of the workspace to delete, which can only include letters, numbers, - , and _ . |
Status | Response | Reason(s) |
---|---|---|
204 | No Content | Successfully deleted the workspace |
404 | JSON API error object | Workspace not found, or user unauthorized to perform workspace delete |
409 | JSON API error object | Workspace is not safe to delete because it is managing resources |
Force Delete a workspace
During a force delete, HCP Terraform removes the specified workspace without checking whether it is managing resources. We recommend using the safe delete endpoint instead, when possible.
Warning: Terraform cannot track or manage the workspace's infrastructure after deletion. We recommend destroying the workspace's infrastructure before you delete it.
By default, only organization owners can force delete workspaces. Organization owners can also update [organization's settings](/terraform/cloud-docs/users-teams organizations/organizations#general) to let workspace admins force delete their own workspaces.
You can use two endpoints to force delete a workspace, which behave identically. One endpoint identifies the workspace with its workspace ID and the other endpoint identifies the workspace with its name and organization.
DELETE /workspaces/:workspace_id
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace to delete |
DELETE /organizations/:organization_name/workspaces/:name
Parameter | Description |
---|---|
:organization_name | The name of the organization the workspace belongs to. |
:name | The name of the workspace to delete, which can only include letters, numbers, - , and _ . |
Status | Response | Reason(s) |
---|---|---|
204 | No Content | Successfully deleted the workspace |
403 | JSON API error object | Not authorized to perform a force delete on the workspace |
404 | JSON API error object | Workspace not found, or user unauthorized to perform workspace delete |
Sample Request
$ 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
Lock a workspace
This endpoint locks a workspace.
POST /workspaces/:workspace_id/actions/lock
Parameter | Description |
---|---|
:workspace_id | The workspace ID to lock. Obtain this from the workspace settings or the Show Workspace endpoint. |
Status | Response | Reason(s) |
---|---|---|
200 | JSON API document (type: "workspaces" ) | Successfully locked the workspace |
404 | JSON API error object | Workspace not found, or user unauthorized to perform action |
409 | JSON API error object | Workspace already locked |
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
reason | string | "" | The reason for locking the workspace. |
Sample Payload
{
"reason": "Locking workspace-1"
}
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/lock
Sample Response
{
"data": {
"id": "ws-6jrRyVDv1J8zQMB5",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-status": null,
"auto-destroy-activity-duration": null,
"inherits-project-auto-destroy": null,
"created-at": "2021-08-16T21:22:49.566Z",
"description": null,
"environment": "default",
"execution-mode": "agent",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:22:49.566Z",
"last-assessment-result-at" : "2021-08-17T21:20:12.908Z",
"locked": true,
"locked-reason": null,
"name": "workspace-1",
"oauth-client-name": null,
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"updated-at": "2021-08-16T21:22:49.566Z",
"vcs-repo": null,
"vcs-repo-identifier": null,
"working-directory": null,
"workspace-kpis-runs-count": 8,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1",
"self-html": "/app/my-organization/workspaces/workspace-1"
},
"relationships": {
"agent-pool": {
"data": {
"id": "apool-QxGd2tRjympfMvQc",
"type": "agent-pools"
}
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
},
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Unlock a workspace
This endpoint unlocks a workspace. Unlocking a workspace sets the current state version to the latest finalized intermediate state version. If intermediate state versions are available, but HCP Terraform has not yet finalized the latest intermediate state version, the unlock will fail with a 503 response. For this particular error, it's recommended to retry the unlock operation for a short period of time until the platform finalizes the state version. If you must force-unlock a workspace under these conditions, ensure that state was saved successfully by inspecting the latest state version using the State Version List API
POST /workspaces/:workspace_id/actions/unlock
Parameter | Description |
---|---|
:workspace_id | The workspace ID to unlock. Obtain this from the workspace settings or the Show Workspace endpoint. |
Status | Response | Reason(s) |
---|---|---|
200 | JSON API document (type: "workspaces" ) | Successfully unlocked the workspace |
404 | JSON API error object | Workspace not found, or user unauthorized to perform action |
409 | JSON API error object | Workspace already unlocked, or locked by a different user |
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request POST \
https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/unlock
Sample Response
{
"data": {
"id": "ws-6jrRyVDv1J8zQMB5",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-status": null,
"auto-destroy-activity-duration": null,
"inherits-project-auto-destroy": null,
"created-at": "2021-08-16T21:22:49.566Z",
"description": null,
"environment": "default",
"execution-mode": "agent",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:22:49.566Z",
"last-assessment-result-at" : "2021-08-17T21:20:12.908Z",
"locked": true,
"locked-reason": null,
"name": "workspace-1",
"oauth-client-name": null,
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"updated-at": "2021-08-16T21:22:49.566Z",
"vcs-repo": null,
"vcs-repo-identifier": null,
"working-directory": null,
"workspace-kpis-runs-count": 8,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1",
"self-html": "/app/my-organization/workspaces/workspace-1"
},
"relationships": {
"agent-pool": {
"data": {
"id": "apool-QxGd2tRjympfMvQc",
"type": "agent-pools"
}
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
},
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Force Unlock a workspace
This endpoint force unlocks a workspace. Only users with admin access are authorized to force unlock a workspace.
POST /workspaces/:workspace_id/actions/force-unlock
Parameter | Description |
---|---|
:workspace_id | The workspace ID to force unlock. Obtain this from the workspace settings or the Show Workspace endpoint. |
Status | Response | Reason(s) |
---|---|---|
200 | JSON API document (type: "workspaces" ) | Successfully force unlocked the workspace |
404 | JSON API error object | Workspace not found, or user unauthorized to perform action |
409 | JSON API error object | Workspace already unlocked |
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request POST \
https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/force-unlock
Sample Response
{
"data": {
"id": "ws-KTuq99JSzgmDSvYj",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"apply-duration-average": null,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-activity-duration": null,
"created-at": "2021-08-16T21:50:58.726Z",
"description": null,
"environment": "default",
"execution-mode": "remote",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:50:58.726Z",
"locked": false,
"locked-reason": "",
"name": "workspace-2",
"oauth-client-name": "github example",
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"display-identifier": "example/terraform-test-proj",
"identifier": "example/terraform-test-proj",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"repository-http-url": "https://github.com/example/terraform-test-proj",
"service-provider": "github",
"tags-regex": null,
"webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"
},
"vcs-repo-identifier": "example/terraform-test-proj",
"working-directory": "",
"workspace-kpis-runs-count": null,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2",
"self-html": "/app/my-organization/workspaces/workspace-2"
},
"relationships": {
"relationships": {
"agent-pool": {
"data": null
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Assign an SSH key to a workspace
This endpoint assigns an SSH key to a workspace.
PATCH /workspaces/:workspace_id/relationships/ssh-key
Parameter | Description |
---|---|
:workspace_id | The workspace ID to assign the SSH key to. Obtain this from the workspace settings or the Show Workspace endpoint. |
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "workspaces" . | |
data.attributes.id | string | The SSH key ID to assign. Obtain this from the ssh-keys endpoint. |
Sample Payload
{
"data": {
"attributes": {
"id": "sshkey-GxrePWre1Ezug7aM"
},
"type": "workspaces"
}
}
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key
Sample Response
{
"data": {
"id": "ws-KTuq99JSzgmDSvYj",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"apply-duration-average": null,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-activity-duration": null,
"created-at": "2021-08-16T21:50:58.726Z",
"description": null,
"environment": "default",
"execution-mode": "remote",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:50:58.726Z",
"locked": false,
"locked-reason": "",
"name": "workspace-2",
"oauth-client-name": "github example",
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"display-identifier": "example/terraform-test-proj",
"identifier": "example/terraform-test-proj",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"repository-http-url": "https://github.com/example/terraform-test-proj",
"service-provider": "github",
"tags-regex": null,
"webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"
},
"vcs-repo-identifier": "example/terraform-test-proj",
"working-directory": "",
"workspace-kpis-runs-count": null,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2",
"self-html": "/app/my-organization/workspaces/workspace-2"
},
"relationships": {
"relationships": {
"agent-pool": {
"data": null
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Unassign an SSH key from a workspace
This endpoint unassigns the currently assigned SSH key from a workspace.
PATCH /workspaces/:workspace_id/relationships/ssh-key
Parameter | Description |
---|---|
:workspace_id | The workspace ID to assign the SSH key to. Obtain this from the workspace settings or the Show Workspace endpoint. |
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "workspaces" . | |
data.attributes.id | string | Must be null . |
Sample Payload
{
"data": {
"attributes": {
"id": null
},
"type": "workspaces"
}
}
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key
Sample Response
{
"data": {
"id": "ws-KTuq99JSzgmDSvYj",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"apply-duration-average": null,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-activity-duration": null,
"created-at": "2021-08-16T21:50:58.726Z",
"description": null,
"environment": "default",
"execution-mode": "remote",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:50:58.726Z",
"locked": false,
"locked-reason": "",
"name": "workspace-2",
"oauth-client-name": "github example",
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"display-identifier": "example/terraform-test-proj",
"identifier": "example/terraform-test-proj",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"repository-http-url": "https://github.com/example/terraform-test-proj",
"service-provider": "github",
"tags-regex": null,
"webhook-url": "https://app.terraform.io/webhooks/vcs/704ac743-df64-4b8e-b9a3-a4c5fe1bec87"
},
"vcs-repo-identifier": "example/terraform-test-proj",
"working-directory": "",
"workspace-kpis-runs-count": null,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2",
"self-html": "/app/my-organization/workspaces/workspace-2"
},
"relationships": {
"relationships": {
"agent-pool": {
"data": null
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null
},
"remote-state-consumers": {
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/relationships/remote-state-consumers"
}
},
"ssh-key": {
"data": {
"id": "sshkey-hjy7ndEkmCtn31ps",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-hjy7ndEkmCtn31ps"
}
},
"locked-by": {
"data": {
"id": "user-hjy7ndEkmCtn31ps",
"type": "users"
},
"links": {
"related": "/api/v2/users/user-hjy7ndEkmCtn31ps"
}
},
"vars": {
"data": [
{
"id": "var-hjy7ndEkmCtn31ps",
"type": "vars"
}
]
},
}
}
}
Get Remote State Consumers
GET /workspaces/:workspace_id/relationships/remote-state-consumers
Parameter | Description |
---|---|
:workspace_id | The workspace ID to get remote state consumers for. Obtain this from the workspace settings or the Show Workspace endpoint. |
This endpoint retrieves the list of other workspaces that are allowed to access the given workspace's state during runs.
- If
global-remote-state
is set to false for the workspace, this will return the list of other workspaces that are specifically authorized to access the workspace's state. - If
global-remote-state
is set to true, this will return a list of every workspace in the organization except for the subject workspace.
The list returned by this endpoint is subject to the caller's normal workspace permissions; it will not include workspaces that the provided API token is unable to read.
Query Parameters
This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [
as %5B
and ]
as %5D
if your tooling doesn't automatically encode URLs.
Parameter | Description |
---|---|
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 workspaces per page. |
Sample Request
$ curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/remote-state-consumers
Sample Response
{
"data": [
{
"id": "ws-6jrRyVDv1J8zQMB5",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"allow-destroy-plan": true,
"assessments-enabled": false,
"auto-apply": false,
"auto-apply-run-trigger": false,
"auto-destroy-at": null,
"auto-destroy-status": null,
"auto-destroy-activity-duration": null,
"inherits-project-auto-destroy": null,
"created-at": "2021-08-16T21:22:49.566Z",
"description": null,
"environment": "default",
"execution-mode": "agent",
"file-triggers-enabled": true,
"global-remote-state": false,
"latest-change-at": "2021-08-16T21:22:49.566Z",
"last-assessment-result-at" : "2021-08-17T21:20:12.908Z",
"locked": true,
"locked-reason": null,
"name": "workspace-1",
"oauth-client-name": null,
"operations": true,
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-run": true,
"can-read-run": true,
"can-read-variable": true,
"can-update-variable": true,
"can-read-state-versions": true,
"can-read-state-outputs": true,
"can-create-state-versions": true,
"can-queue-apply": true,
"can-lock": true,
"can-unlock": true,
"can-force-unlock": true,
"can-read-settings": true,
"can-manage-tags": true,
"can-manage-run-tasks": true,
"can-force-delete": true,
"can-manage-assessments": true,
"can-manage-ephemeral-workspaces": false,
"can-read-assessment-results": true,
"can-queue-destroy": true
},
"apply-duration-average": 35000,
"plan-duration-average": 53000,
"policy-check-failures": null,
"queue-all-runs": false,
"resource-count": 10,
"run-failures": 3,
"source": "tfe-api",
"source-name": null,
"source-url": null,
"speculative-enabled": true,
"structured-run-output-enabled": true,
"tag-names": [],
"terraform-version": "1.9.4",
"trigger-prefixes": [],
"updated-at": "2021-08-16T21:22:49.566Z",
"vcs-repo": null,
"vcs-repo-identifier": null,
"working-directory": null,
"workspace-kpis-runs-count": 8,
"setting-overwrites": {
"execution-mode": true,
"agent-pool": true
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1",
"self-html": "/app/my-organization/workspaces/workspace-1"
},
"relationships": {
"agent-pool": {
"data": {
"id": "apool-QxGd2tRjympfMvQc",
"type": "agent-pools"
}
},
"current-configuration-version": {
"data": null
},
"current-run": {
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"latest-run": { // Deprecated; same as current-run
"data": {
"id": "run-hjy7ndEkmCtn31ps",
"type": "runs"
},
"links": {
"related": "/api/v2/runs/run-hjy7ndEkmCtn31ps"
}
},
"current-state-version": {
"data": {
"id": "sv-hjy7ndEkmCtn31ps",
"type": "state-versions"
},
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version"
}
},
"current-configuration-version": {
"data": {
"id": "cv-hjy7ndEkmCtn31ps",
"type": "configuration-versions"
},
"links": {
"related": "/api/v2/configuration-versions/cv-hjy7ndEkmCtn31ps"
}
},
"current-assessment-result": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"outputs": {
"data": [
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
},
{
"id": "wsout-hjy7ndEkmCtn31ps",
"type": "workspace-outputs"
}
],
"links": {
"related": "/api/v2/workspaces/ws-6jrRyVDv1J8zQMB5/current-state-version-outputs"
}
},
"project": {
"data": {
"id": "prj-hjy7ndEkmCtn31ps",
"type": "projects"
}
},
"readme": {
"data": null