Variable Sets API
A variable set is a resource that allows you to reuse the same variables across multiple workspaces and projects. For example, you could define a variable set of provider credentials and automatically apply it to a selection of workspaces, all workspaces in a project, or all workspaces in an organization.
You need read variables
permission to view the variables for a particular workspace and to view the variable sets in the owning organization. To create or edit variable sets, your team must have Manage Workspace
organization access.
Create a Variable Set
POST organizations/:organization_name/varsets
Parameter | Description |
---|---|
:organization_name | The name of the organization the workspace belongs to. |
Request Body
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.name | string | The name of the variable set. | |
data.description | string | "" | Text displayed in the UI to contextualize the variable set and its purpose. |
data.global | boolean | false | When true, Terraform Cloud automatically applies the variable set to all current and future workspaces in the organization. |
data.priority | boolean | false | When true, the variables in the set override any other variable values with a more specific scope, including values set on the command line. |
data.relationships.workspaces | array | `[]` | Array of references to workspaces that the variable set should be assigned to. |
data.relationships.projects | array | `[]` | Array of references to projects that the variable set should be assigned to. |
data.relationships.vars | array | `[]` | Array of complete variable definitions that comprise the variable set. |
Terraform Cloud does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to create a global variable set that contains conflicting variables.
Status | Response | Reason(s) |
---|---|---|
200 | JSON API document | Successfully added variable set |
404 | JSON API error object | Organization not found, or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
Sample Response
Update a Variable Set
PUT/PATCH varsets/:varset_id
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Terraform Cloud does not allow global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to create a global variable set that contains conflicting variables.
Request Body
Key path | Type | Default | Description |
---|---|---|---|
data.name | string | The name of the variable set. | |
data.description | string | Text displayed in the UI to contextualize the variable set and its purpose. | |
data.global | boolean | When true, Terraform Cloud automatically applies the variable set to all current and future workspaces in the organization. | |
data.priority | boolean | false | When true, the variables in the set override any other variable values set with a more specific scope, including values set on the command line. |
data.relationships.workspaces | array | Optional Array of references to workspaces that the variable set should be assigned to. Sending an empty array clears all workspace assignments. | |
data.relationships.projects | array | Optional Array of references to projects that the variable set should be assigned to. Sending an empty array clears all project assignments. | |
data.relationships.vars | array | Optional Array of complete variable definitions to add to the variable set. |
Status | Response | Reason(s) |
---|---|---|
200 | JSON API document | Successfully updated variable set |
404 | JSON API error object | Organization or variable set not found, or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
Sample Response
Delete a Variable Set
DELETE varsets/:varset_id
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Sample Request
On success, this endpoint responds with no content.
Show Variable Set
Fetch details about the specified variable set.
GET varsets/:varset_id
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Sample Request
Sample Response
List Variable Sets
List all variable sets for an organization.
GET organizations/:organization_name/varsets
Parameter | Description |
---|---|
:organization_name | The name of the organization the variable sets belong to |
List all variable sets for a project. This includes global variable sets from the project's organization.
GET projects/:project_id/varsets
Parameter | Description |
---|---|
:project_id | The project ID |
List all variable sets for a workspace. This includes global variable sets from the workspace's organization and variable sets attached to the project this workspace is contained within.
GET workspaces/:workspace_id/varsets
Parameter | Description |
---|---|
:workspace_id | The workspace ID |
Query Parameters
All of the list endpoints support 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 returns the first page. |
page[size] | Optional. If omitted, the endpoint returns 20 varsets per page. |
Sample Response
Variable Relationships
Add Variable
POST varsets/:varset_external_id/relationships/vars
Parameter | Description |
---|---|
:varset_id | The variable set ID |
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 "vars" . | |
data.attributes.key | string | The name of the variable. | |
data.attributes.value | string | "" | The value of the variable. |
data.attributes.description | string | The description of the variable. | |
data.attributes.category | string | Whether this is a Terraform or environment variable. Valid values are "terraform" or "env" . | |
data.attributes.hcl | bool | false | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. |
data.attributes.sensitive | bool | false | Whether the value is sensitive. If true, variable is not visible in the UI. |
Terraform Cloud does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to add a conflicting variable to a global variable set.
Status | Response | Reason(s) |
---|---|---|
200 | JSON API document | Successfully added variable to variable set |
404 | JSON API error object | Variable set not found, or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
Sample Respone
Update a Variable in a Variable Set
PATCH varsets/:varset_id/relationships/vars/:var_id
Parameter | Description |
---|---|
:varset_id | The variable set ID |
:var_id | The ID of the variable to delete |
Terraform Cloud does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to add a conflicting variable to a global variable set.
Status | Response | Reason(s) |
---|---|---|
200 | JSON API document | Successfully updated variable for variable set |
404 | JSON API error object | Variable set not found, or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
Sample Response
Delete a Variable in a Variable Set
DELETE varsets/:varset_id/relationships/vars/:var_id
Parameter | Description |
---|---|
:varset_id | The variable set ID |
:var_id | The ID of the variable to delete |
Sample Request
On success, this endpoint responds with no content.
List Variables in a Variable Set
GET varsets/:varset_id/relationships/vars
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Sample Response
Apply Variable Set to Workspaces
Accepts a list of workspaces to add the variable set to.
POST varsets/:varset_id/relationships/workspaces
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data[].type | string | Must be "workspaces" | |
data[].id | string | The id of the workspace to add the variable set to |
Status | Response | Reason(s) |
---|---|---|
204 | Successfully added variable set to the requested workspaces | |
404 | JSON API error object | Variable set not found or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
Remove a Variable Set from Workspaces
Accepts a list of workspaces to remove the variable set from.
DELETE varsets/:varset_id/relationships/workspaces
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data[].type | string | Must be "workspaces" | |
data[].id | string | The id of the workspace to delete the variable set from |
Status | Response | Reason(s) |
---|---|---|
204 | Successfully removed variable set from the requested workspaces | |
404 | JSON API error object | Variable set not found or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
Apply Variable Set to Projects
Accepts a list of projects to add the variable set to. When you apply a variable set to a project, all the workspaces in that project will have the variable set applied to them.
POST varsets/:varset_id/relationships/projects
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data[].type | string | Must be "projects" | |
data[].id | string | The id of the project to add the variable set to |
Status | Response | Reason(s) |
---|---|---|
204 | Successfully added variable set to the requested projects | |
404 | JSON API error object | Variable set not found or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
Remove a Variable Set from Projects
Accepts a list of projects to remove the variable set from.
DELETE varsets/:varset_id/relationships/projects
Parameter | Description |
---|---|
:varset_id | The variable set ID |
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data[].type | string | Must be "projects" | |
data[].id | string | The id of the project to delete the variable set from |
Status | Response | Reason(s) |
---|---|---|
204 | Successfully removed variable set from the requested projects | |
404 | JSON API error object | Variable set not found or user unauthorized to perform action |
422 | JSON API error object | Problem with payload or request; details provided in the error object |
Sample Payload
Sample Request
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:
Resource Name | Description |
---|---|
vars | Show each variable in a variable set and all of their attributes including id , key , value , sensitive , category , hcl , created_at , and description . |