Admin OPA Versions API
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.
The OPA Versions Admin API lets site administrators manage which versions of OPA are available to the HCP Terraform users within their enterprise.
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-versionsSample 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-L4oe7rNwn7J4E5YrSample 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-L4oe7rNwn7J4E5YrSample 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