Key version configuration 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) version represents the specific version of your key management service (KMS) key. A HYOK configuration is associated with a specific key, but that key can have multiple versions. Having multiple key versions lets you rotate and manage the keys in your key management service without creating a new HYOK configuration for that key.

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

List HYOK customer key versions for an HYOK configuration

GET /api/v2/hyok-configurations/:hyok_configuration_id/hyok-customer-key-versions

Parameter	Description
`hyok_configuration_id`	The ID of the HYOK configuration to which the HYOK customer key versions belong.

Status	Response	Reason
200	JSON API document	Successfully fetched HYOK customer key version.
404	JSON API error object	HYOK customer key version 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.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 HYOK configurations per page.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/hyok-configurations/:hyok_configuration_id/hyok-customer-key-versions

Sample response

{
    "data": {
        "id": "keyv-emT4uwmo1B8B81Jt",
        "type": "hyok-customer-key-versions",
        "attributes": {
            "key-version": "3",
            "created-at": "2025-04-30T16:09:52.399Z",
            "status": "available",
            "error": null,
            "workspaces-secured": 0
        },
        "relationships": {
            "hyok-configuration": {
                "data": {
                    "id": "hyokc-B4ae7Tzsy52QzMTA",
                    "type": "hyok-configurations"
                }
            }
        }
    }
}

Show HYOK customer key versions

GET /api/v2/hyok-customer-key-versions/:id

Parameter	Description
`id`	The ID of the HYOK customer key version.

Status	Response	Reason
200	JSON API document	Successfully fetched HYOK customer key version.
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-customer-key-versions/: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
`data.attributes.created-at`	string	Creation timestamp
`data.attributes.status`	string	Relevant status for this HYOK customer key version. Possible values: `available`, `revoking`, `revoked`, `revocation_failed`
`data.attributes.error`	string	A supplementary error message that provides additional context when the `status` is `revocation_failed`.
`data.attributes.workspaces-secured`	integer	The number of HCP Terraform workspaces that currently have Data Encryption Keys (DEKs) secured with this HYOK customer key version
`data.relationships.hyok-configuration.data.id`	string	The ID of the HYOK configuration that this HYOK customer key version belongs to.

Sample response

{
    "data": {
        "id": "keyv-emT4uwmo1B8B81Jt",
        "type": "hyok-customer-key-versions",
        "attributes": {
            "key-version": "3",
            "created-at": "2025-04-30T16:09:52.399Z",
            "status": "available",
            "error": null,
            "workspaces-secured": 0
        },
        "relationships": {
            "hyok-configuration": {
                "data": {
                    "id": "hyokc-B4ae7Tzsy52QzMTA",
                    "type": "hyok-configurations"
                }
            }
        }
    }
}

Revoke HYOK customer key versions

POST /api/v2/hyok-customer-key-versions/:hyok_customer_key_version_id/actions/revoke

Parameter	Description
`hyok_customer_key_version_id`	The ID of the HYOK customer key version to revoke.

Status	Response	Reason
202		Successfully triggered the revocation of the HYOK customer key version.
404	JSON API error object	HYOK customer key version not found, or user unauthorized to perform action.
422	JSON API error object	No agent running, malformed request body (missing attributes, wrong types, etc.).

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/hyok-customer-key-versions/:hyok_configuration_id/actions/revoke

Sample payload

{}

Sample response

HTTP/1.1 202 Accepted
Content-Length: 0

Check for New HYOK customer key versions

GET /api/v2/hyok-configurations/:hyok_configuration_id/key-versions?refresh

Parameter	Description
`hyok_configuration_id`	The ID of the HYOK configuration.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/hyok-configurations/:hyok_configuration_id/key-versions?refresh

Sample response

{
    "data": [
        {
            "id": "keyv-bUW9Za7LfRStunTp",
            "type": "hyok-customer-key-versions",
            "attributes": {
                "key-version": "10",
                "created-at": "2025-05-01T14:28:18.595Z",
                "status": "available",
                "error": null,
                "workspaces-secured": 0
            },
            "relationships": {
                "hyok-configuration": {
                    "data": {
                        "id": "hyokc-tPLXkKbURnrVvMFs",
                        "type": "hyok-configurations"
                    }
                }
            }
        }
    ],
    "links": {
        "self": "https://tfcdev-f3054ebe.ngrok.app/api/v2/hyok-configurations/hyokc-tPLXkKbURnrVvMFs/hyok-customer-key-versions?id=hyokc-tPLXkKbURnrVvMFs\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20\u0026refresh=true",
        "first": "https://tfcdev-f3054ebe.ngrok.app/api/v2/hyok-configurations/hyokc-tPLXkKbURnrVvMFs/hyok-customer-key-versions?id=hyokc-tPLXkKbURnrVvMFs\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20\u0026refresh=true",
        "prev": null,
        "next": null,
        "last": "https://tfcdev-f3054ebe.ngrok.app/api/v2/hyok-configurations/hyokc-tPLXkKbURnrVvMFs/hyok-customer-key-versions?id=hyokc-tPLXkKbURnrVvMFs\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20\u0026refresh=true"
    },
    "meta": {
        "pagination": {
            "current-page": 1,
            "page-size": 20,
            "prev-page": null,
            "next-page": null,
            "total-pages": 1,
            "total-count": 1
        }
    }
}