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

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

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

List all Sentinel versions

GET /api/v2/admin/sentinel-versions

This endpoint lists all known versions of Sentinel.

StatusResponseReason
200JSON API document (type: "sentinel-versions")Successfully lists Sentinel versions.
404JSON API error objectClient 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.

ParameterDescription
filter[version]Optional. A query string. This will find an exact Sentinel version matching the version queried. This option takes precedence over search queries.
search[version]Optional. A search query string. This will search for Sentinel 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 Sentinel versions per page.

Sample Request

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

Sample Response

{
  "data": [
    {
      "id": "tool-L4oe7rNwn7J4E5Yr",
      "type": "sentinel-versions",
      "attributes": {
        "version": "0.22.1",
        "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
        "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
        "deprecated": false,
        "deprecated-reason": null,
        "official": true,
        "enabled": true,
        "beta": false,
        "usage": 0,
        "created-at": "2023-08-23T22:34:24.561Z"
      }
    }
  ],
  "links": {
    "self": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": "https://tfe.example.com/api/v2/admin/sentinel-versions?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "last": "https://tfe.example.com/api/v2/admin/sentinel-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 a Sentinel version

POST /api/v2/admin/sentinel-versions

StatusResponseReason
201JSON API document (type: "sentinel-versions")The Sentinel version was successfully created.
404JSON API error objectThe client is not an administrator.
422JSON API error objectValidation 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 pathTypeDefaultDescription
data.typestringMust be "sentinel-versions".
data.attributes.versionstringA semantic version string in N.N.N or N.N.N-bundleName format ("0.11.0" or "0.12.20-beta1").
data.attributes.urlstringThe URL where you can download the 64-bit Linux binary of this version.
data.attributes.shastringThe SHA-256 checksum of the compressed Sentinel binary.
data.attributes.deprecatedboolfalseWhether or not this version of Sentinel is deprecated.
data.attributes.deprecated-reasonstringnullAdditional context about why a version of Sentinel is deprecated. Field is null unless deprecated is true.
data.attributes.officialboolfalseWhether or not this is an official release of Sentinel.
data.attributes.enabledbooltrueWhether or not this version of Sentinel is enabled for use in Terraform Cloud.
data.attributes.betaboolfalseWhether or not this version of Sentinel is a beta pre-release.

Sample Payload

{
  "data": {
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "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/sentinel-versions

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Show a Sentinel version

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

ParameterDescription
:idThe ID of the Sentinel version to show.
StatusResponseReason
200JSON API document (type: "sentinel-versions")Successfully shows the specified Sentinel version.
404JSON API error objectCould not find the specified Sentinel version, or 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/sentinel-versions/tool-L4oe7rNwn7J4E5Yr

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "official": true,
      "deprecated": false,
      "deprecated-reason": null,
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Update a Sentinel version

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

ParameterDescription
:idThe ID of the Sentinel version to update.
StatusResponseReason
200JSON API document (type: "sentinel-versions")The Sentinel version was successfully updated.
404JSON API error objectCould not find the specified Sentinel version, or client is not an administrator.
422JSON API error objectValidation 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 pathTypeDefaultDescription
data.typestringMust be "sentinel-versions".
data.attributes.versionstring(previous value)A semantic version string in N.N.N or N.N.N-bundleName format ("0.11.0", "0.12.20-beta1").
data.attributes.urlstring(previous value)The URL you can download the 64-bit Linux binary of this version.
data.attributes.shastring(previous value)The SHA-256 checksum of the compressed Sentinel binary.
data.attributes.officialbool(previous value)Whether or not this is an official release of Sentinel.
data.attributes.deprecatedbool(previous value)Whether or not this version of Sentinel is deprecated.
data.attributes.deprecated-reasonstring(previous value)Additional context about why a version of Sentinel is deprecated.
data.attributes.enabledbool(previous value)Whether or not this version of Sentinel is enabled for use in Terraform Cloud.
data.attributes.betabool(previous value)Whether or not this version of Sentinel is a beta pre-release.

Sample Payload

{
  "data": {
    "type": "sentinel-versions",
    "attributes": {
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Sentinel. 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/sentinel-versions/tool-L4oe7rNwn7J4E5Yr

Sample Response

{
  "data": {
    "id": "tool-L4oe7rNwn7J4E5Yr",
    "type": "sentinel-versions",
    "attributes": {
      "version": "0.22.1",
      "url": "https://releases.hashicorp.com/sentinel/0.22.1/sentinel_0.22.1_linux_amd64.zip",
      "sha": "0a4a2b2baf46bfeb81d5137b2656b159ccc881487df3bebacd350ea48b53e76c",
      "official": true,
      "deprecated": true,
      "deprecated-reason": "A bug was discovered in this version of Sentinel. Please upgrade as soon as possible",
      "enabled": true,
      "beta": false,
      "usage": 0,
      "created-at": "2023-08-23T22:34:24.561Z"
    }
  }
}

Delete a Sentinel version

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

This endpoint removes a Sentinel version from Terraform Cloud. You cannot remove officially labeled Sentinel versions or any version used by a workspace.

ParameterDescription
:idThe ID of the Sentinel version to delete.
StatusResponseReason
204Empty responseThe Sentinel version was successfully deleted.
404JSON API error objectThe request could not find a matching Sentinel version with the specified ID, or the client is not an administrator.
422JSON API error objectThe request could not remove the Sentinel version because it is an official version or a workspace 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/sentinel-versions/tool-L4oe7rNwn7J4E5Yr