HashiCorp Developer AI Private beta now available Sign up today
Terraform
Terraform Home

You are viewing documentation for version v202308-1. View latest version.

Policy Sets API

Policy Enforcement lets you use the policy-as-code frameworks Sentinel and Open Policy Agent (OPA) to apply policy checks to Terraform Cloud workspaces.

Policy sets let you group related policies by attributes like environment or region. You can then apply each policy set to one or more workspaces. For these workspaces, Terraform Cloud checks every Terraform plan against each policy in the set.

This API provides endpoints to create, read, update, and delete policy sets in a Terraform Cloud organization. To view and manage individual policies, use the Policies API.

Many of these endpoints let you create policy sets from a designated repository in a Version Control System (VCS). For more information about how to configure a policy set VCS repository, refer to Sentinel Policy Set VCS Repositories and OPA Policy Set VCS Repositories.

Instead of connecting Terraform Cloud to a VCS repository, you can use the the Policy Set Versions endpoint to create an entire policy set from a tar.gz file.

Interacting with policy sets requires permission to manage policies. (More about permissions.)

Create a Policy Set

POST /organizations/:organization_name/policy-sets

ParameterDescription
:organization_nameThe organization to create the policy set in. The organization must already exist in the system, and the token authenticating the API request must have permission to manage policies. (More about permissions.)
StatusResponseReason
201JSON API document (type: "policy-sets")Successfully created a policy set
404JSON API error objectOrganization not found, or user unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)

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 pathTypeDefaultDescription
data.typestringMust be "policy-sets".
data.attributes.namestringThe name of the policy set. Can include letters, numbers, -, and _.
data.attributes.descriptionstringnullText describing the policy set's purpose. This field supports Markdown and appears in the Terraform Cloud UI.
data.attributes.globalbooleanfalseWhether Terraform Cloud should automatically apply this policy set to all of an organization's workspaces.
data.attributes.kindstringsentinelThe policy-as-code framework associated with the policy. Valid values are sentinel and opa.
data.attributes.overridablebooleanfalseWhether or not users can override this policy when it fails during a run. Only valid for OPA policies.
data.attributes.vcs-repoobjectnullVCS repository information. When present, Terraform Cloud sources the policies and configuration from the specified VCS repository. This attribute and policies relationships are mutually exclusive, and you cannot use them simultaneously.
data.attributes.vcs-repo.branchstringnullThe branch of the VCS repository where Terraform Cloud should retrieve the policy set. If empty, Terraform Cloud uses the default branch.
data.attributes.vcs-repo.identifierstringThe VCS repository identifier in the format <namespace>/<repo>. For example, hashicorp/my-policy-set. The format for Azure DevOps is <org>/<project>/_git/<repo>.
data.attributes.vcs-repo.oauth-token-idstringThe OAuth Token ID Terraform Cloud should use to connect to the VCS host. This value must not be specified if github-app-installation-id is specified.
data.attributes.vcs-repo.github-app-installation-idstringThe VCS Connection GitHub App Installation to use. Find this ID on the user settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from User Settings within Terraform Cloud. You can not specify this value if oauth-token-id is specified.
data.attributes.vcs-repo.ingress-submodulesbooleanfalseWhether Terraform Cloud should instantiate repository submodules when retrieving the policy set.
data.attributes.policies-pathstringnullThe VCS repository subdirectory that contains the policies for this policy set. Terraform Cloud ignores files and directories outside of this sub-path and does not update the policy set when those files change. This attribute is only valid when you specify a VCS repository for the policy set.
data.relationships.workspaces.data[]array[object][]A list of resource identifier objects that defines which workspaces are associated with the policy set. These objects must contain id and type properties, and the type property must be workspaces. For example, { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }. Obtain workspace IDs from the workspace's settings page or the Show Workspace endpoint. You can only specify this attribute when data.attributes.global is false.
data.relationships.policies.data[]array[object][]A list of resource identifier objects that defines which policies are members of the policy set. These objects must contain id and type properties, and the type property must be policies. For example, { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }.

Sample Payload

{
  "data": {
    "type": "policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "global": false,
      "kind": "sentinel",
      "policies-path": "/policy-sets/foo",
      "vcs-repo": {
        "branch": "master",
        "identifier": "hashicorp/my-policy-sets",
        "ingress-submodules": false,
        "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
      }
    },
    "relationships": {
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    }
  }
}

Sample payload with individual policy relationships

{
  "data": {
    "type": "policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false
    },
    "relationships": {
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "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/policy-sets

Sample Response

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "workspace-count": 1,
      "policies-path": "/policy-sets/foo",
      "versioned": true,
      "vcs-repo": {
        "branch": "master",
        "identifier": "hashicorp/my-policy-sets",
        "ingress-submodules": false,
        "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
      },
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

Sample response with individual policy relationships

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "policy-count": 1,
      "workspace-count": 1,
      "versioned": false,
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

List Policy Sets

GET /organizations/:organization_name/policy-sets

ParameterDescription
:organization_nameThe organization to list policy sets for.
StatusResponseReason
200JSON API document (type: "policy-sets")Request was successful
404JSON API error objectOrganization not found, or user unauthorized to perform action

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.

ParameterDescription
filter[versioned]Optional. Allows filtering policy sets based on whether they are versioned (VCS-managed or API-managed), or use individual policy relationships. Accepts a boolean true/false value. A true value returns versioned sets, and a false value returns sets with individual policy relationships. If omitted, all policy sets are returned.
filter[kind]Optional. If specified, restricts results to those with the matching policy kind value. Valid values are sentinel and opa.
includeOptional. Allows including related resource data. Value must be a comma-separated list containing one or more of workspaces, policies, newest_version, or current_version. See the relationships section for details.
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 policy sets per page.
search[name]Optional. Allows searching the organization's policy sets by name.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/organizations/my-organization/policy-sets

Sample Response

{
  "data": [
    {
      "id":"polset-3yVQZvHzf5j3WRJ1",
      "type":"policy-sets",
      "attributes": {
        "name": "production",
        "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
        "kind": "sentinel",
        "global": false,
        "workspace-count": 1,
        "policies-path": "/policy-sets/foo",
        "versioned": true,
        "vcs-repo": {
          "branch": "master",
          "identifier": "hashicorp/my-policy-sets",
          "ingress-submodules": false,
          "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
        },
        "created-at": "2018-09-11T18:21:21.784Z",
        "updated-at": "2018-09-11T18:21:21.784Z"
      },
      "relationships": {
        "organization": {
          "data": { "id": "my-organization", "type": "organizations" }
        },
        "workspaces": {
          "data": [
            { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
          ]
        }
      },
      "links": {
        "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
      }
    }
  ]
}

Sample response with individual policy relationships

{
  "data": [
    {
      "id":"polset-3yVQZvHzf5j3WRJ1",
      "type":"policy-sets",
      "attributes": {
        "name": "production",
        "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
        "kind": "sentinel",
        "global": false,
        "policy-count": 1,
        "workspace-count": 1,
        "versioned": false,
        "created-at": "2018-09-11T18:21:21.784Z",
        "updated-at": "2018-09-11T18:21:21.784Z"
      },
      "relationships": {
        "organization": {
          "data": { "id": "my-organization", "type": "organizations" }
        },
        "policies": {
          "data": [
            { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
          ]
        },
        "workspaces": {
          "data": [
            { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
          ]
        }
      },
      "links": {
        "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
      }
    },
  ]
}

Show a Policy Set

GET /policy-sets/:id

ParameterDescription
:idThe ID of the policy set to show. Use the "List Policy Sets" endpoint to find IDs.
StatusResponseReason
200JSON API document (type: "policy-sets")The request was successful
404JSON API error objectPolicy set not found or user unauthorized to perform action
ParameterDescription
includeOptional. Allows including related resource data. Value must be a comma-separated list containing one or more of workspaces, policies, newest_version, or current_version. See the relationships section for details.

Sample Request

curl --request GET \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1?include=current_version

Sample Response

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "policy-count": 0,
      "workspace-count": 1,
      "policies-path": "/policy-sets/foo",
      "versioned": true,
      "vcs-repo": {
        "branch": "master",
        "identifier": "hashicorp/my-policy-sets",
        "ingress-submodules": false,
        "oauth-token-id": "ot-7Fr9d83jWsi8u23A"
      },
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "current-version": {
        "data": {
          "id": "polsetver-m4yhbUBCgyDVpDL4",
          "type": "policy-set-versions"
        }
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  },
  "included": [
    {
      "id": "polsetver-m4yhbUBCgyDVpDL4",
      "type": "policy-set-versions",
      "attributes": {
        "source": "github",
        "status": "ready",
        "status-timestamps": {
          "ready-at": "2019-06-21T21:29:48+00:00",
          "ingressing-at": "2019-06-21T21:29:47+00:00"
        },
        "error": null,
        "ingress-attributes": {
          "commit-sha": "8766a423cb902887deb0f7da4d9beaed432984bb",
          "commit-url": "https://github.com/hashicorp/my-policy-sets/commit/8766a423cb902887deb0f7da4d9beaed432984bb",
          "identifier": "hashicorp/my-policy-sets"
        },
        "created-at": "2019-06-21T21:29:47.792Z",
        "updated-at": "2019-06-21T21:29:48.887Z"
      },
      "relationships": {
        "policy-set": {
          "data": {
            "id": "polset-a2mJwtmKygrA11dh",
            "type": "policy-sets"
          }
        }
      },
      "links": {
        "self": "/api/v2/policy-set-versions/polsetver-E4S7jz8HMjBienLS"
      }
    }
  ]
}

Sample response with individual policy relationships

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "production",
      "description": "This set contains policies that should be checked on all production infrastructure workspaces.",
      "kind": "sentinel",
      "global": false,
      "policy-count": 1,
      "workspace-count": 1,
      "versioned": false,
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z",
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

Note: The data.relationships.workspaces object refers to workspaces directly attached to the policy set. This key is omitted for policy sets marked as global, which are implicitly related to all of the organization's workspaces.

Update a Policy Set

PATCH /policy-sets/:id

ParameterDescription
:idThe ID of the policy set to update. Use the "List Policy Sets" endpoint to find IDs.
StatusResponseReason
200JSON API document (type: "policy-sets")The request was successful
404JSON API error objectPolicy set not found or user unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)

Request Body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "policy-sets".
data.attributes.namestring(previous value)The name of the policy set. Can include letters, numbers, -, and _.
data.attributes.descriptionstring(previous value)A description of the set's purpose. This field supports Markdown and will be rendered in the Terraform Cloud UI.
data.attributes.globalboolean(previous value)Whether or not this policies in this set should be checked on all of the organization's workspaces, or only on workspaces directly attached to the set.
data.attributes.vcs-repoobject(previous value)VCS repository information. When present, the policies and configuration will be sourced from the specified VCS repository instead of being defined within Terraform Cloud. Note that this option and policies relationships are mutually exclusive and may not be used simultaneously.
data.attributes.vcs-repo.branchstring(previous value)The branch of the VCS repo. If empty, the VCS provider's default branch value will be used.
data.attributes.vcs-repo.identifierstring(previous value)The identifier of the VCS repository in the format <namespace>/<repo>. For example, on GitHub, this would be something like hashicorp/my-policy-set. The format for Azure DevOps is <org>/<project>/_git/<repo>.
data.attributes.vcs-repo.oauth-token-idstring(previous value)The OAuth Token ID to use to connect to the VCS host.
data.attributes.vcs-repo.ingress-submodulesboolean(previous value)Determines whether repository submodules will be instantiated during the clone operation.
data.attributes.policies-pathboolean(previous value)The subdirectory of the attached VCS repository that contains the policies for this policy set. Files and directories outside of this sub-path will be ignored, and changes to those unrelated files won't cause the policy set to be updated. This option may only be specified when a VCS repo is present.
data.relationships.workspacesarray[object](previous value)An array of references to workspaces that the policy set should be assigned to. Sending an empty array clears all workspace assignments. You can only specify this attribute when data.attributes.global is false.

Sample Payload

{
  "data": {
    "type": "policy-sets"
    "attributes": {
      "name": "workspace-scoped-policy-set",
      "description": "Policies added to this policy set will be enforced on specified workspaces",
      "global": false
    },
    "relationships": {
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "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/policy-sets/polset-3yVQZvHzf5j3WRJ1

Sample Response

{
  "data": {
    "id":"polset-3yVQZvHzf5j3WRJ1",
    "type":"policy-sets",
    "attributes": {
      "name": "workspace-scoped-policy-set",
      "description": "Policies added to this policy set will be enforced on specified workspaces",
      "global": false,
      "kind": "sentinel",
      "policy-count": 1,
      "workspace-count": 1,
      "versioned": false,
      "created-at": "2018-09-11T18:21:21.784Z",
      "updated-at": "2018-09-11T18:21:21.784Z"
    },
    "relationships": {
      "organization": {
        "data": { "id": "my-organization", "type": "organizations" }
      },
      "policies": {
        "data": [
          { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }
        ]
      },
      "workspaces": {
        "data": [
          { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
        ]
      }
    },
    "links": {
      "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1"
    }
  }
}

Add Policies to the Policy Set

POST /policy-sets/:id/relationships/policies

ParameterDescription
:idThe ID of the policy set to add policies to. Use the "List Policy Sets" endpoint to find IDs.
StatusResponseReason
204No ContentThe request was successful
404JSON API error objectPolicy set not found or user unauthorized to perform action
422JSON API error objectMalformed request body (one or more policies not found, wrong types, etc.)

Note: This endpoint may only be used when there is no VCS repository associated with the policy set.

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 pathTypeDefaultDescription
data[]array[object]A list of resource identifier objects that defines which policies will be added to the set. These objects must contain id and type properties, and the type property must be policies (e.g. { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }).

Sample Payload

{
  "data": [
    { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" },
    { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies

Attach a Policy Set to workspaces

POST /policy-sets/:id/relationships/workspaces

ParameterDescription
:idThe ID of the policy set to attach to workspaces. Use the "List Policy Sets" endpoint to find IDs.

Note: Policy sets marked as global cannot be attached to individual workspaces.

StatusResponseReason
204No ContentThe request was successful
404JSON API error objectPolicy set not found or user unauthorized to perform action
422JSON API error objectMalformed request body (one or more workspaces not found, wrong types, etc.)

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 pathTypeDefaultDescription
data[]array[object]A list of resource identifier objects that defines the workspaces the policy set will be attached to. These objects must contain id and type properties, and the type property must be workspaces (e.g. { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }).

Sample Payload

{
  "data": [
    { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" },
    { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces

Remove Policies from the Policy Set

DELETE /policy-sets/:id/relationships/policies

ParameterDescription
:idThe ID of the policy set to remove policies from. Use the "List Policy Sets" endpoint to find IDs.
StatusResponseReason
204No ContentThe request was successful
404JSON API error objectPolicy set not found or user unauthorized to perform action
422JSON API error objectMalformed request body (wrong types, etc.)

Note: This endpoint may only be used when there is no VCS repository associated with the policy set.

Request Body

This DELETE endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data[]array[object]A list of resource identifier objects that defines which policies will be removed from the set. These objects must contain id and type properties, and the type property must be policies (e.g. { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }).

Sample Payload

{
  "data": [
    { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" },
    { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies

Detach the Policy Set from workspaces

DELETE /policy-sets/:id/relationships/workspaces

ParameterDescription
:idThe ID of the policy set to detach from workspaces. Use the "List Policy Sets" endpoint to find IDs.

Note: Policy sets marked as global cannot be detached from individual workspaces.

StatusResponseReason
204No ContentThe request was successful
404JSON API error objectPolicy set not found or user unauthorized to perform action
422JSON API error objectMalformed request body (wrong types, etc.)

Request Body

This DELETE endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data[]array[object]A list of resource identifier objects that defines which workspaces the policy set will be detached from. These objects must contain id and type properties, and the type property must be workspaces (e.g. { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }). Obtain workspace IDs from the workspace settings or the Show Workspace endpoint.

Sample Payload

{
  "data": [
    { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" },
    { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }
  ]
}

Sample Request

curl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces

Delete a Policy Set

DELETE /policy-sets/:id

ParameterDescription
:idThe ID of the policy set to delete. Use the "List Policy Sets" endpoint to find IDs.
StatusResponseReason
204No ContentSuccessfully deleted the policy set
404JSON API error objectPolicy set not found, or user unauthorized to perform action

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-3yVQZvHzf5j3WRJ1

Create a Policy Set Version

For versioned policy sets which have no VCS repository attached, versions of policy code may be uploaded directly to the API by creating a new policy set version and, in a subsequent request, uploading a tarball (tar.gz) of data to it.

POST /policy-sets/:id/versions

ParameterDescription
:idThe ID of the policy set to create a new version for.
StatusResponseReason
201JSON API document (type: "policy-set-versions")The request was successful.
404JSON API error objectPolicy set not found or user unauthorized to perform action
422JSON API error objectThe policy set does not support uploading versions.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/versions

Sample Response

{
  "data": {
    "id": "polsetver-cXciu9nQwmk9Cfrn",
    "type": "policy-set-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "pending",
      "status-timestamps": {},
      "error": null,
      "created-at": "2019-06-28T23:53:15.875Z",
      "updated-at": "2019-06-28T23:53:15.875Z"
    },
    "relationships": {
      "policy-set": {
        "data": {
          "id": "polset-ws1CZBzm2h5K6ZT5",
          "type": "policy-sets"
        }
      }
    },
    "links": {
      "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn",
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..."
    }
  }
}

The upload link URL in the above response is valid for one hour after creation. Make a PUT request to this URL directly, sending the policy set contents in tar.gz format as the request body. Once uploaded successfully, you can request the Show Policy Set endpoint again to verify that the status has changed from pending to ready.

Upload Policy Set Versions

PUT https://archivist.terraform.io/v1/object/<UNIQUE OBJECT ID>

The URL is provided in the upload attribute in the policy-set-versions resource.

Sample Request

In the example below, policy-set.tar.gz is the local filename of the policy set version file to upload.

curl \
  --header "Content-Type: application/octet-stream" \
  --request PUT \
  --data-binary @policy-set.tar.gz \
  https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox...

Show a Policy Set Version

GET /policy-set-versions/:id

ParameterDescription
:idThe ID of the policy set version to show.
StatusResponseReason
200JSON API document (type: "policy-set-versions")The request was successful.
404JSON API error objectPolicy set version not found or user unauthorized to perform action

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  https://app.terraform.io/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn

Sample Response

{
  "data": {
    "id": "polsetver-cXciu9nQwmk9Cfrn",
    "type": "policy-set-versions",
    "attributes": {
      "source": "tfe-api",
      "status": "pending",
      "status-timestamps": {},
      "error": null,
      "created-at": "2019-06-28T23:53:15.875Z",
      "updated-at": "2019-06-28T23:53:15.875Z"
    },
    "relationships": {
      "policy-set": {
        "data": {
          "id": "polset-ws1CZBzm2h5K6ZT5",
          "type": "policy-sets"
        }
      }
    },
    "links": {
      "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn",
      "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..."
    }
  }
}

The upload link URL in the above response is valid for one hour after the created_at timestamp of the policy set version. Make a PUT request to this URL directly, sending the policy set contents in tar.gz format as the request body. Once uploaded successfully, you can request the Show Policy Set Version endpoint again to verify that the status has changed from pending to ready.

Available Related Resources

The GET endpoints above can optionally return related resources for policy sets, if requested with the include query parameter. The following resource types are available:

Resource NameDescription
current_versionThe most recent successful policy set version.
newest_versionThe most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors.
policiesIndividually managed policies which are associated with the policy set.
workspacesThe workspaces to which the policy set applies.

The following resource types may be included for policy set versions:

Resource NameDescription
policy_setThe policy set associated with the specified policy set version.

Relationships

The following relationships may be present in various responses for policy sets:

Resource NameDescription
current-versionThe most recent successful policy set version.
newest-versionThe most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors.
organizationThe organization associated with the specified policy set.
policiesIndividually managed policies which are associated with the policy set.
workspacesThe workspaces to which the policy set applies.

The following relationships may be present in various responses for policy set versions:

Resource NameDescription
policy-setThe policy set associated with the specified policy set version.