» 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 Workspaces" 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.auto-apply |
boolean | false |
Whether to automatically apply changes when a Terraform plan is successful, with some exceptions. |
data.attributes.description |
string | (nothing) | A description for the workspace. |
data.attributes.execution-mode |
string | remote |
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. |
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.file-triggers-enabled |
boolean | true |
Whether to filter runs based on the changed files in a VCS push. If enabled, the working-directory and trigger-prefixes describe a set of paths which must contain changes for a VCS push to trigger a run. If disabled, any push will trigger a run. |
data.attributes.source-name (beta) |
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 (beta) |
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.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.speculative-enabled |
boolean | true | Whether this workspace allows speculative plans. Setting this to false prevents Terraform Cloud from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. |
data.attributes.terraform-version |
string | (nothing) | The version of Terraform to use for this workspace. Upon creating a workspace, the latest version is selected unless otherwise specified (e.g. "0.11.1" ). |
data.attributes.trigger-prefixes |
array | [] |
List of repository-root-relative paths which should be tracked for changes, in addition to the working directory. |
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.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.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.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.ingress-submodules |
boolean | false |
Whether submodules should be fetched when cloning the VCS repository. |
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 . |
» 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": "skierkowski/terraform-test-proj",
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"branch": ""
}
},
"type": "workspaces"
}
}
For a monorepo
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",
"trigger-prefixes": ["/modules", "/vendor"],
"working-directory": "/networking",
"vcs-repo": {
"identifier": "skierkowski/terraform-test-proj-monorepo",
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"branch": ""
}
},
"type": "workspaces"
}
}
Using Terraform Cloud Agents
Terraform Cloud Agents are a solution to allow Terraform Cloud to communicate with isolated, private, or on-premises infrastructure.
{
"data": {
"attributes": {
"name":"workspace-1",
"execution-mode": "agent",
"agent-pool-id": "apool-ZjT6A7mVFm5WHT5a"
}
},
"type": "workspaces"
}
» 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
Without a VCS repository
{
"data": {
"id": "ws-YnyXLq9fy38afEeb",
"type": "workspaces",
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-18T00:43:59.384Z",
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-1",
"permissions": {
"can-update": true,
"can-destroy": false,
"can-queue-destroy": false,
"can-queue-run": false,
"can-update-variable": false,
"can-lock": false,
"can-read-settings": true
},
"queue-all-runs": false,
"terraform-version": "0.11.0",
"trigger-prefixes": [],
"vcs-repo": null,
"working-directory": "",
"execution-mode": "agent"
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"ssh-key": {
"data": null
},
"latest-run": {
"data": null
},
"agent-pool": {
"data": {
"id": "apool-ZjT6A7mVFm5WHT5a",
"type": "agent-pools"
}
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1"
}
}
}
With a VCS repository
{
"data": {
"id": "ws-SihZTyXKfNXUWuUa",
"type": "workspaces",
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": true,
"created-at": "2017-11-02T23:55:16.142Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-2",
"permissions": {
"can-update": true,
"can-destroy": false,
"can-queue-destroy": false,
"can-queue-run": false,
"can-update-variable": false,
"can-lock": false,
"can-read-settings": true
},
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"identifier": "skierkowski/terraform-test-proj",
"branch": "",
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ",
"ingress-submodules": false
},
"working-directory": null,
"execution-mode": "agent"
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"ssh-key": {
"data": null
},
"latest-run": {
"data": null
},
"agent-pool": {
"data": {
"id": "apool-ZjT6A7mVFm5WHT5a",
"type": "agent-pools"
}
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2"
}
}
}
» 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.
Note that workspaces without an associated VCS repository only use the auto-apply
, terraform-version
, and working-directory
.
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.description |
string | (previous value) | A description for the workspace. |
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.auto-apply |
boolean | (previous value) | Whether to automatically apply changes when a Terraform plan is successful, with some exceptions. |
data.attributes.allow-destroy-plan |
boolean | (previous value) | Whether destroy plans can be queued on 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. |
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.file-triggers-enabled |
boolean | (previous value) | Whether to filter runs based on the changed files in a VCS push. If enabled, the working-directory and trigger-prefixes describe a set of paths which must contain changes for a VCS push to trigger a run. If disabled, any push will trigger a run. |
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 speculative plans. Setting this to false prevents Terraform Cloud from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. |
data.attributes.terraform-version |
string | (previous value) | The version of Terraform to use for this workspace. |
data.attributes.trigger-prefixes |
array | (previous value) | List of repository-root-relative paths which should be tracked for changes, in addition to the working directory. |
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.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.vcs-repo.oauth-token-id |
string | (previous value) | The VCS Connection (OAuth Connection + Token) to use. This ID can be obtained from the oauth-tokens endpoint. |
data.attributes.vcs-repo.branch |
string | (previous value) | The repository branch that Terraform will execute from. |
data.attributes.vcs-repo.ingress-submodules |
boolean | (previous value) | Whether submodules should be fetched when cloning the VCS repository. |
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 . |
» Sample Payload
{
"data": {
"attributes": {
"name": "workspace-2",
"terraform_version": "0.11.1",
"working-directory": "",
"vcs-repo": {
"identifier": "skierkowski/terraform-test-proj",
"branch": "",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ"
}
},
"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-SihZTyXKfNXUWuUa",
"type": "workspaces",
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:24:05.997Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-2",
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"identifier": "skierkowski/terraform-test-proj",
"branch": "",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ"
},
"working-directory": ""
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"ssh-key": {
"data": null
},
"latest-run": {
"data": null
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2"
}
}
}
» 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. |
» 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-SihZTyXKfNXUWuUa",
"type": "workspaces",
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:24:05.997Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-2",
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"ingress-submodules": false
},
"working-directory": ""
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"ssh-key": {
"data": null
},
"latest-run": {
"data": null
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2"
}
},
{
"id": "ws-YnyXLq9fy38afEeb",
"type": "workspaces",
"attributes": {
"auto-apply": false,
"allow-destroy-plan":false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:23:53.765Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-1",
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"ingress-submodules": false
},
"working-directory": ""
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"ssh-key": {
"data": null
},
"latest-run": {
"data": null
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-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 _ . |
» 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-mD5bmJ8ry3uTzuHi",
"type": "workspaces",
"attributes": {
"actions": {
"is-destroyable": true
},
"auto-apply": false,
"allow-destroy-plan": true,
"created-at": "2018-03-08T22:30:00.404Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-1",
"permissions": {
"can-update": true,
"can-destroy": true,
"can-queue-destroy": true,
"can-queue-run": true,
"can-update-variable": true,
"can-lock": true,
"can-read-settings": true
},
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.11.3",
"trigger-prefixes": [],
"working-directory": null
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"latest-run": {
"data": null
},
"current-run": {
"data": null
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-1"
}
}
}
» Delete a workspace
A workspace can be deleted via two endpoints, which behave identically. One refers to a workspace by its ID, and the other by 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 _ . |
» 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": {
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:23:53.765Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": true,
"name": "workspace-2",
"permissions": {
"can-destroy": true,
"can-lock": true,
"can-queue-destroy": true,
"can-queue-run": true,
"can-read-settings": true,
"can-update": true,
"can-update-variable": true
},
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"identifier": "my-organization/my-repository",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ"
},
"working-directory": null
},
"id": "ws-SihZTyXKfNXUWuUa",
"relationships": {
"locked-by": {
"data": {
"id": "my-user",
"type": "users"
},
"links": {
"related": "/api/v2/users/my-user"
}
}
},
"type": "workspaces"
}
}
» Unlock a workspace
This endpoint unlocks a workspace.
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": {
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:23:53.765Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-2",
"permissions": {
"can-destroy": true,
"can-lock": true,
"can-queue-destroy": true,
"can-queue-run": true,
"can-read-settings": true,
"can-update": true,
"can-update-variable": true
},
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"identifier": "my-organization/my-repository",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ"
},
"working-directory": null
},
"id": "ws-SihZTyXKfNXUWuUa",
"type": "workspaces"
}
}
» 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": {
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:23:53.765Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-2",
"permissions": {
"can-destroy": true,
"can-lock": true,
"can-queue-destroy": true,
"can-queue-run": true,
"can-read-settings": true,
"can-update": true,
"can-update-variable": true
},
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"identifier": "my-organization/my-repository",
"ingress-submodules": false,
"oauth-token-id": "ot-hmAyP66qk2AMVdbJ"
},
"working-directory": null
},
"id": "ws-SihZTyXKfNXUWuUa",
"type": "workspaces"
}
}
» 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": {
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:24:05.997Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-2",
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"ingress-submodules": false
},
"working-directory": ""
},
"id": "ws-SihZTyXKfNXUWuUa",
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2"
},
"relationships": {
"latest-run": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"ssh-key": {
"data": {
"id": "sshkey-GxrePWre1Ezug7aM",
"type": "ssh-keys"
},
"links": {
"related": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM"
}
}
},
"type": "workspaces"
}
}
» 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": {
"attributes": {
"auto-apply": false,
"allow-destroy-plan": false,
"can-queue-destroy-plan": false,
"created-at": "2017-11-02T23:24:05.997Z",
"description": null,
"environment": "default",
"file-triggers-enabled": true,
"locked": false,
"name": "workspace-2",
"queue-all-runs": false,
"source": "tfe-ui",
"source-name": null,
"source-url": null,
"terraform-version": "0.10.8",
"trigger-prefixes": [],
"vcs-repo": {
"branch": "",
"ingress-submodules": false
},
"working-directory": ""
},
"id": "ws-erEAnPmgtm5mJr77",
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/workspace-2"
},
"relationships": {
"latest-run": {
"data": null
},
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"ssh-key": {
"data": null
}
},
"type": "workspaces"
}
}
» Available Related Resources
The GET endpoints above can optionally return related resources, if requested with the include
query parameter. The following resource types are available:
organization
- The full organization record.current_run
- Additional information about the current run.current_run.plan
- The plan used in the current run.current_run.configuration_version
- The configuration used in the current run.current_run.configuration_version.ingress_attributes
- The commit information used in the current run.