Encrypted data key API reference

Note

Hold your own key is available on the HCP Terraform Premium edition. Refer to HCP Terraform pricing for details.

A hold your own key (HYOK) encrypted data key is the key that your key management service (KMS) encrypts. HCP Terraform uses this key to encrypt your Terraform artifacts, such as state and plan files. Your KMS key remains under your control and outside of HCP Terraform networks.

To learn more about hold your own key, refer to the Overview.

Show HYOK encrypted data key

GET /api/v2/hyok-encrypted-data-keys/:id

Parameter	Description
`id`	The ID of the HYOK encrypted data key.

Status	Response	Reason
200	JSON API document	Successfully fetched HYOK encrypted data key.
404	JSON API error object	HYOK customer key version not found, or user unauthorized to perform action.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/hyok-encrypted-data-keys/:id

Response body

The endpoint will return a JSON object with the following properties.

Key path	Type	Description
`data.attributes.key-version`	string	The key version of your Key Management Service (KMS) key.
`data.attributes.created-at`	string	Creation timestamp
`data.attributes.encrypted-dek`	string	The encrypted Data Encryption Key (DEK) is the key that is used to HYOK encrypt your HCP Terraform artifacts. This DEK is encrypted using your Key Management Service (KMS) key encryption key.
`data.attributes.customer-key-name`	string	Refers to the HYOK configuration name.
`data.relationships.hyok-customer-key-version.data.id`	string	The ID of the HYOK customer key version that this HYOK encrypted data key belongs to.

Sample response

{
    "data": {
        "id": "dek-M8KCQM8pjAZKmpmW",
        "type": "hyok-encrypted-data-keys",
        "attributes": {
            "encrypted-dek": "dmF1bHQ6djE6NWpSdGhpRmUwRzFGRDhzZnlUeGcyaVBoVW0rVXJXMDBJblJVNjQ3aEpzeU5KMXF1RkV2T3FWYmJTTDF0SFRJbGdySFk4WkJ3dzJKcjVHNXQ=",
            "created-at": "2025-04-28T15:39:32.157Z",
            "customer-key-name": "tf-rocket-hyok-oasis"
        },
        "relationships": {
            "hyok-customer-key-version": {
                "data": {
                    "id": "keyv-PJJ5biGx2xGmk1ko",
                    "type": "hyok-customer-key-versions"
                }
            }
        }
    }
}