Policy Set Parameters API

Note: Sentinel policies are a paid feature, available as part of the Team & Governance upgrade package. Learn more about Terraform Cloud pricing here.

This set of APIs covers create, update, list and delete operations on parameters.

Create a Parameter

POST /policy-sets/:policy_set_id/parameters

Parameter	Description
`:policy_set_id`	The ID of the policy set to create the parameter in.

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 parameter.
`data.attributes.value`	string	`""`	The value of the parameter.
`data.attributes.category`	string		The category of the parameters. Must be `"policy-set"`.
`data.attributes.sensitive`	bool	`false`	Whether the value is sensitive. If true then the parameter is written once and not visible thereafter.

Sample Payload

{
  "data": {
    "type":"vars",
    "attributes": {
      "key":"some_key",
      "value":"some_value",
      "category":"policy-set",
      "sensitive":false
    }
  }
}

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/policy-sets/polset-u3S5p2Uwk21keu1s/parameters

Sample Response

{
  "data": {
    "id":"var-EavQ1LztoRTQHSNT",
    "type":"vars",
    "attributes": {
      "key":"some_key",
      "value":"some_value",
      "sensitive":false,
      "category":"policy-set"
    },
    "relationships": {
      "configurable": {
        "data": {
          "id":"pol-u3S5p2Uwk21keu1s",
          "type":"policy-sets"
        },
        "links": {
          "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s"
        }
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-EavQ1LztoRTQHSNT"
    }
  }
}

List Parameters

GET /policy-sets/:policy_set_id/parameters

Parameter	Description
`:policy_set_id`	The ID of the policy set to list parameters for.

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. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 parameters per page.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters"

Sample Response

{
  "data": [
    {
      "id":"var-AD4pibb9nxo1468E",
      "type":"vars",
      "attributes": {
        "key":"name",
        "value":"hello",
        "sensitive":false,
        "category":"policy-set",
      },
      "relationships": {
        "configurable": {
          "data": {
            "id":"pol-u3S5p2Uwk21keu1s",
            "type":"policy-sets"
          },
          "links": {
            "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s"
          }
        }
      },
      "links": {
        "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-AD4pibb9nxo1468E"
      }
    }
  ]
}

Update Parameters

PATCH /policy-sets/:policy_set_id/parameters/:parameter_id

Parameter	Description
`:policy_set_id`	The ID of the policy set that owns the parameter.
`:parameter_id`	The ID of the parameter to be updated.

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	Description
`data.type`	string	Must be `"vars"`.
`data.id`	string	The ID of the parameter to update.
`data.attributes`	object	New attributes for the parameter. This object can include `key`, `value`, `category` and `sensitive` properties, which are described above under create a parameter. All of these properties are optional; if omitted, a property will be left unchanged.

Sample Payload

{
  "data": {
    "id":"var-yRmifb4PJj7cLkMG",
    "attributes": {
      "key":"name",
      "value":"mars",
      "category":"policy-set",
      "sensitive": false
    },
    "type":"vars"
  }
}

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/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG

Sample Response

{
  "data": {
    "id":"var-yRmifb4PJj7cLkMG",
    "type":"vars",
    "attributes": {
      "key":"name",
      "value":"mars",
      "sensitive":false,
      "category":"policy-set",
    },
    "relationships": {
      "configurable": {
        "data": {
          "id":"pol-u3S5p2Uwk21keu1s",
          "type":"policy-sets"
        },
        "links": {
          "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s"
        }
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG"
    }
  }
}

Delete Parameters

DELETE /policy-sets/:policy_set_id/parameters/:parameter_id

Parameter	Description
`:policy_set_id`	The ID of the policy set that owns the parameter.
`:parameter_id`	The ID of the parameter to be deleted.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG