/admin/opa-versions API reference for Terraform Enterprise | Terraform

The /opa-versions endpoint lets site administrators manage which versions of OPA you can use to enforce policies.

Terraform Enterprise Only: The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance.

List all OPA versions

GET /api/v2/admin/opa-versions

This endpoint lists all known versions of OPA.

Status	Response	Reason
200	JSON API document (`type: "opa-versions"`)	Successfully lists OPA versions.
404	JSON API error object	Client is not an administrator.

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
`filter[version]`	Optional. A query string. This will find an exact OPA version matching the version queried. This option takes precedence over search queries.
`search[version]`	Optional. A search query string. This will search for OPA versions matching the version number queried.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 OPA versions per page.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/v2/admin/opa-versions"

Sample Response

{
  "data": [
    {
      "id": "tool-L4oe7rNwn7J4E5Yr",
      "type": "opa-versions",
      "attributes": {
        "version": "0.55.0",
        "url": "https://github.com/open-policy-agent/opa/releases/download/v0.55.0/opa_linux_arm64_static",
        "sha": "d19603df4ab619e98cc515084f62b839464ee5bff61383d1df7724db8a7027a9",
        "deprecated": false,
        "deprecated-reason": null,
        "official": true,
        "enabled": true,
        "beta": false,
        "usage": 0,
        "created-at": "2023-08-23T22:34:24.561Z"
      }
    },
    {
      "id": "tool-qcbYn12vuRKPgPpy",
      "type": "opa-versions",
      "attributes": {
        "version": "0.54.0",
        "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static",
        "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8",
        "deprecated": false,
        "deprecated-reason": null,
        "official": true,
        "enabled": true,
        "beta": false,
        "usage": 2,
        "created-at": "2023-08-23T22:34:24.561Z"
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "last": "https://tfe.example.com/api/v2/admin/opa-versions?page%5Bnumber%5D=4&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "prev-page": null,
      "next-page": 2,
      "total-pages": 4,
      "total-count": 70
    }
  }
}

Create an OPA version

POST /api/v2/admin/opa-versions

Status	Response	Reason
201	JSON API document (`type: "opa-versions"`)	The OPA version was successfully created.
404	JSON API error object	Client is not an administrator.
422	JSON API error object	Validation errors.

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 `"opa-versions"`.
`data.attributes.version`	string		A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`).
`data.attributes.url`	string		The URL where you can download the 64-bit Linux binary of this version.
`data.attributes.sha`	string		The SHA-256 checksum of the OPA binary.
`data.attributes.deprecated`	bool	`false`	Whether or not this version of OPA is deprecated.
`data.attributes.deprecated-reason`	string	`null`	Additional context about why a version of OPA is deprecated. Field is null unless deprecated is `true`.
`data.attributes.official`	bool	`false`	Whether or not this is an official release of OPA.
`data.attributes.enabled`	bool	`true`	Whether or not this version of OPA is enabled for use in HCP Terraform.
`data.attributes.beta`	bool	`false`	Whether or not this version of OPA is a beta pre-release.

Sample Payload

{
  "data": {
    "type": "opa-versions",
    "attributes": {
      "version": "0.11.8",
      "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static",
      "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8",
      "official": true,
      "enabled": true,
      "beta": 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/admin/opa-versions

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "opa-versions",
    "attributes": {
      "version": "0.54.0",
      "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static",
      "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Show an OPA version

GET /api/v2/admin/opa-versions/:id

Parameter	Description
`:id`	The ID of the OPA version to show.

Status	Response	Reason
200	JSON API document (`type: "opa-versions"`)	The request was successful, returns the OPA version with the matching ID.
404	JSON API error object	The request could not find a matching OPA version with the specified ID, or the client is not an administrator.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/admin/opa-versions/tool-L4oe7rNwn7J4E5Yr

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "opa-versions",
    "attributes": {
      "version": "0.54.0",
      "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static",
      "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Update an OPA version

PATCH /api/v2/admin/opa-versions/:id

Parameter	Description
`:id`	The ID of the OPA version to update.

Status	Response	Reason
200	JSON API document (`type: "opa-versions"`)	The OPA version was successfully updated.
404	JSON API error object	The request could not find a matching OPA version with the specified ID, or the client is not an administrator.
422	JSON API error object	Validation errors.

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 path	Type	Default	Description
`data.type`	string		Must be `"opa-versions"`.
`data.attributes.version`	string	(previous value)	A semantic version string in N.N.N or N.N.N-bundleName format (`"0.11.0"` or `"0.12.20-beta1"`).
`data.attributes.url`	string	(previous value)	The URL where you can download the 64-bit Linux binary of this version.
`data.attributes.sha`	string	(previous value)	The SHA-256 checksum of the OPA binary.
`data.attributes.official`	bool	(previous value)	Whether or not this is an official release of OPA.
`data.attributes.deprecated`	bool	(previous value)	Whether or not this version of OPA is deprecated.
`data.attributes.deprecated-reason`	string	(previous value)	Additional context about why a version of OPA is deprecated.
`data.attributes.enabled`	bool	(previous value)	Whether or not this version of OPA is enabled for use in HCP Terraform.
`data.attributes.beta`	bool	(previous value)	Whether or not this version of OPA is a beta pre-release.

Sample Payload

{
  "data": {
    "type": "opa-versions",
    "attributes": {
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of OPA. Please upgrade as soon as possible"
    }
  }
}

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/admin/opa-versions/tool-L4oe7rNwn7J4E5Yr

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "opa-versions",
    "attributes": {
      "version": "0.54.0",
      "url": "https://github.com/open-policy-agent/opa/releases/download/v0.54.0/opa_linux_arm64_static",
      "sha": "883e22c082508e2f95ba25333559ba8a5c38c9c5ef667314e132c9d8451450d8",
      "official": true,
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of OPA. Please upgrade as soon as possible",
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Delete an OPA version

DELETE /api/v2/admin/opa-versions/:id

This endpoint removes an OPA version from HCP Terraform. You cannot remove officially labeled OPA versions or versions used by a workspace or policy set.

Parameter	Description
`:id`	The ID of the OPA version to delete.

Status	Response	Reason
204	Empty response	The OPA version was successfully deleted.
404	JSON API error object	The request could not find a matching OPA version with the specified ID, or the client is not an administrator.
422	JSON API error object	The request could not remove the OPA version because it is an official version or a workspace or policy set uses it.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/admin/opa-versions/tool-L4oe7rNwn7J4E5Yr

Admin OPA Versions API

List all OPA versions

Query Parameters

Sample Request

Sample Response

Create an OPA version

Request Body

Sample Payload

Sample Request

Sample Response

Show an OPA version

Sample Request

Sample Response

Update an OPA version

Request Body

Sample Payload

Sample Request

Sample Response

Delete an OPA version

Sample Request