Hold Your Own Key (HYOK) API Documentation #588

dominic-retli-hashi · 2025-07-17T20:08:13Z

https://hashicorp.atlassian.net/jira/software/c/projects/TF/boards/438?selectedIssue=TF-26977

…g onto api endpoints next

…ed to clean this up and add descriptions for the request bodies and such

…tails

hashicorp-cla-app · 2025-07-17T20:08:28Z

All committers have signed the CLA.

github-actions · 2025-07-17T20:08:57Z

Vercel Previews Deployed

Name	Status	Preview	Updated (UTC)
Dev Portal	✅ Ready (Inspect)	Visit Preview	Tue Jul 22 21:07:33 UTC 2025
Unified Docs API	✅ Ready (Inspect)	Visit Preview	Tue Jul 22 21:00:51 UTC 2025

github-actions · 2025-07-17T21:11:27Z

Broken Link Checker

Summary

Status	Count
🔍 Total	146
✅ Successful	145
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	0
❓ Unknown	0
🚫 Errors	1

Errors per input

Errors in content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx

[404] https://unified-docs-frontend-preview-fkl8iqdtd-hashicorp.vercel.app/terraform/enterprise/admin/application/module-sharing | Network error: Not Found
Full Github Actions output

JarrettSpiker · 2025-07-21T18:58:20Z

content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/organizations.mdx

@@ -431,7 +431,8 @@ Properties without a default value are required.
 | `data.attributes.assessments-enforced`                                    | boolean | (false)          | Whether or not to compel health assessments for all eligible workspaces. When true, health assessments occur on all compatible workspaces, regardless of the value of the workspace setting `assessments-enabled`. When false, health assessments only occur for workspaces that opt in by setting `assessments-enabled: true`.                                                    |
 | `data.attributes.allow-force-delete-workspaces`                           | boolean | (false)          | Whether workspace administrators can [delete workspaces with resources under management](/terraform/enterprise/users-teams-organizations/organizations#general). If false, only organization owners may delete these workspaces.                                                                                                                                                   |
 | `data.attributes.default-execution-mode`                                  | string  | `remote`         | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use by default. Valid values are `remote`, `local`, and `agent`.                                                                                                                                                                                                                               |
-| `data.attributes.default-agent-pool-id`                                   | string  | (previous value) | Required when `default-execution-mode` is set to `agent`. The ID of the agent pool belonging to the organization. Do _not_ specify this value if you set `execution-mode` to `remote` or `local`.                                                                                                                                                                                  |


I believe that these changes to existing files (organizations, plans, state versions, and workspaces) should all be in this directory https://github.com/hashicorp/web-unified-docs/tree/main/content/terraform-docs-common/docs/cloud-docs/api-docs

My understanding is that we only modify the terraform-enterprise directory when we need to change a specific TFE version's docs. Otherwise it gets automatically populated as part of the TFE release

juliannatetreault

This is looking great so far! ⭐ I left some suggestions and some questions--let me know what you think or if you have questions about any of them!

...terraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/aws-oidc-configurations.mdx

...rraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/azure-oidc-configurations.mdx

content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/organizations.mdx

content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/plans.mdx

juliannatetreault · 2025-07-21T20:01:27Z

content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/state-versions.mdx

@@ -65,6 +66,7 @@ Some of the information returned in a state version API object might be **popula
 | `terraform-version`              | The Terraform version that created this state. Populated asynchronously.                                                                                                                                                                                                     |
 | `vcs-commit-sha`                 | The SHA of the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository.                                                                                                                      |
 | `vcs-commit-url`                 | A link to the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository.                                                                                                                       |
+| `hyok-encrypted-data-key`       | A reference                                                                                                                                                                                                                                                                  |


Is this missing some information here? 🤔

content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/state-versions.mdx

content/terraform-enterprise/v202507-1/docs/enterprise/api-docs/workspaces.mdx

Co-authored-by: Julianna <[email protected]>

…t directory

…larity Co-authored-by: Julianna <[email protected]>

Co-authored-by: Julianna <[email protected]>

….com:hashicorp/web-unified-docs into dominicretli/TF-26977/hyok-api-documentation

JarrettSpiker · 2025-07-23T15:10:33Z

content/terraform-docs-common/data/cloud-docs-nav-data.json

+      {
+        "title": "Hold Your Own Key",
+        "routes": [
+          { "title": "Hold Your Own Key", "path": "api-docs/hold-your-own-key/hold-your-own-key" },
+          { "title": "Configurations", "path": "api-docs/hold-your-own-key/hyok-configurations" },
+          { "title": "Customer Key Versions", "path": "api-docs/hold-your-own-key/hyok-customer-key-versions" },
+          { "title": "Encrypted Data Keys", "path": "api-docs/hold-your-own-key/hyok-encrypted-data-keys" },
+          { "title": "Vault OIDC Configurations", "path": "api-docs/hold-your-own-key/vault-oidc-configurations" },
+          { "title": "AWS OIDC Configurations", "path": "api-docs/hold-your-own-key/aws-oidc-configurations" },
+          { "title": "Azure OIDC Configurations", "path": "api-docs/hold-your-own-key/azure-oidc-configurations" },
+          { "title": "GCP OIDC Configurations", "path": "api-docs/hold-your-own-key/gcp-oidc-configurations" }
+        ]
+      },


@rkoron007 or @robin-norwood do you know if it's possible to have these pages only appear for the HCP Terraform docs, but not for TFE? I see how to do individual sections of a page (with the ) but Im not sure if we can exclude entire pages?

JarrettSpiker · 2025-07-23T15:13:55Z

...terraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/aws-oidc-configurations.mdx

+[JSON API error object]: https://jsonapi.org/format/#error-objects
+
+# AWS OIDC Configuration API reference
+


It could be worth calling out that these configurations are only available on HCP Terraform (not TFE), and that they require Premium Tier

Suggested change

Hold Your Own Key (HYOK) is only available on the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform. This includes the management of OIDC configurations.

JarrettSpiker · 2025-07-23T15:14:40Z

...rraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/azure-oidc-configurations.mdx

+[JSON API error object]: https://jsonapi.org/format/#error-objects
+
+# Azure OIDC Configuration API reference
+


Suggested change

Hold Your Own Key (HYOK) is only available on the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform. This includes the management of OIDC configurations.

JarrettSpiker · 2025-07-23T15:15:21Z

...terraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/gcp-oidc-configurations.mdx

+[JSON API error object]: https://jsonapi.org/format/#error-objects
+
+# GCP OIDC Configuration API reference
+


Suggested change

Hold Your Own Key (HYOK) is only available on the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform. This includes the management of OIDC configurations.

JarrettSpiker · 2025-07-23T15:16:21Z

content/terraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/hold-your-own-key.mdx

+---
+
+# Hold Your Own Key (HYOK) API Reference
+Hold Your Own Key, or HYOK, lets you authenticate your own Key Management System (KMS) to encrypt HCP Terraform state and plan data. HCP Terraform agents do the actual work of securing and encrypting artifacts, so neither your key (from your KMS), nor unencrypted secrets need to be uploaded to HCP Terraform, and no out-of-network traffic needs to hit your KMS.


Suggested change

Hold Your Own Key, or HYOK, lets you authenticate your own Key Management System (KMS) to encrypt HCP Terraform state and plan data. HCP Terraform agents do the actual work of securing and encrypting artifacts, so neither your key (from your KMS), nor unencrypted secrets need to be uploaded to HCP Terraform, and no out-of-network traffic needs to hit your KMS.

Hold Your Own Key, or HYOK, lets you authenticate your own Key Management System (KMS) to encrypt HCP Terraform state and plan data. HCP Terraform agents do the actual work of securing and encrypting artifacts, so neither your key (from your KMS), nor unencrypted secrets need to be uploaded to HCP Terraform, and no out-of-network traffic needs to hit your KMS.

HYOK is only available on the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform.)

JarrettSpiker · 2025-07-23T15:25:37Z

content/terraform-docs-common/docs/cloud-docs/api-docs/state-versions.mdx

 | `hosted-json-state-upload-url`   | A URL to which you can upload state data in a [stable format](/terraform/internals/json-format) appropriate for external integrations to consume. You can upload JSON state content once per state version.                                                                  |
 | `hosted-state-upload-url`        | A URL to which you can upload state data in the format used Terraform uses internally. You can upload state data once per state version.                                                                                                                                     |
+| `hyok-encrypted-data-key`        | A reference to the HYOK encrypted data key used to secure this state version.                                                                                                                                                                                                |


Suggested change

| `hyok-encrypted-data-key` | A reference to the HYOK encrypted data key used to secure this state version. |

| `hyok-encrypted-data-key` | A reference to the HYOK encrypted data key used to secure this state version. HCP Terraform only, requires the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform.) |

JarrettSpiker · 2025-07-23T15:25:58Z

content/terraform-docs-common/docs/cloud-docs/api-docs/workspaces.mdx

@@ -141,6 +141,7 @@ By supplying the necessary attributes under a `vcs-repository` object, you can c
 | `data.attributes.vcs-repo` | object  | none | Settings for the workspace's VCS repository. If omitted, the workspace is created without a VCS repo. If included, you must specify at least the `oauth-token-id` and `identifier` keys. |
 | `data.attributes.working-directory`             | string  | (nothing) | A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository. |
 | `data.attributes.setting-overwrites` | object | none | The keys in this object are attributes that have project-level defaults. Each attribute key stores a boolean value which is `false` by default. To overwrite the default inherited value, set an attribute's value to `true`. For example, to set `execution-mode` as the project default, set `setting-overwrites.execution-mode` to `true`. |
+| `data.attributes.hyok-enabled`       | boolean | `false` | Whether this workspace will secure HCP Terraform artifacts using Hold Your Own Key (HYOK) encryption. Once enabled, this can not be disabled. |


Suggested change

| `data.attributes.hyok-enabled` | boolean | `false` | Whether this workspace will secure HCP Terraform artifacts using Hold Your Own Key (HYOK) encryption. Once enabled, this can not be disabled. |

| `data.attributes.hyok-enabled` | boolean | `false` | Whether this workspace will secure HCP Terraform artifacts using Hold Your Own Key (HYOK) encryption. Once enabled, this can not be disabled. HCP Terraform only, requires the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform.) |

JarrettSpiker · 2025-07-23T15:29:56Z

...rraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/azure-oidc-configurations.mdx

+
+| Key path                         | Type    | Default   | Description                                                                                                                                                                                               |
+| -------------------------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data.type`                      | string  |           | Must be `"azure-oidc-configurations"`.                                                                                                                                                                               |


JarrettSpiker · 2025-07-23T15:33:40Z

...terraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/gcp-oidc-configurations.mdx

+
+| Key path                         | Type    | Default   | Description                                                                                                                                                                                               |
+| -------------------------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data.type`                      | string  |           | Must be `"gcp-oidc-configurations"`.                                                                                                                                                                               |


Suggested change

| `data.type` | string | | Must be `"gcp-oidc-configurations"`. |

| `data.type` | string | | Must be `"gcp-oidc-configurations"`. |

| `data.attributes.service-account-email` | string | | The email of your GCP service account, with permissions to encrypt and decrypt using a Cloud KMS key. |

| `data.attributes.workload-provider-name` | string | | The fully qualifies workload provider path. This should be in the format `projects/{project_number}/locations/global/workloadIdentityPools/{workload_identity_pool_id}/providers/{workload_identity_pool_provider_id}`|

| `data.attributes.project-number` | string | | The GCP Project containing the workload provider and service account. |

JarrettSpiker · 2025-07-23T15:46:25Z

...rraform-docs-common/docs/cloud-docs/api-docs/hold-your-own-key/vault-oidc-configurations.mdx

+
+| Key path                         | Type    | Default   | Description                                                                                                                                                                                               |
+| -------------------------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data.type`                      | string  |           | Must be `"vault-oidc-configurations"`.                                                                                                                                                                    |


dominic-retli-hashi added 9 commits July 16, 2025 10:45

WIP - hyok configurations documentations. Completed attributes, movin…

87759ef

…g onto api endpoints next

WIP - added the reamining endpoints for hyok configurations. STill ne…

08d451c

…ed to clean this up and add descriptions for the request bodies and such

WIP - added hyok customer key versions endpoints. Need to add more de…

953a37d

…tails

cleanup, added more info'

783042d

added additional info for hyok customer key versions

e491f25

fixed title for endpoint

c26f71c

added HYOK Encrypted Data Key, other cleanup

459a370

added oidc configurations docs

6dee84e

added HYOK specific information to existing doc pages

849a857

dominic-retli-hashi added 3 commits July 17, 2025 16:15

added hyok docs to the nac

876b894

fix typos

0cdcf92

more cleanup

e138874

dominic-retli-hashi added 6 commits July 18, 2025 09:32

added link to HYOK docs for more info

44e8f64

cleanup

421d89e

more cleanup

52a1291

more cleanup

90282d3

removed my name payload examples

3fbd12e

reorganized hyok docs into subpages

2c0ae84

dominic-retli-hashi changed the title ~~HYOK API Documentation~~ Hold Your Own Key (HYOK) API Documentation Jul 18, 2025

dominic-retli-hashi added 3 commits July 18, 2025 15:55

Removed link to docs that dont yet exist

dec7276

re organize hyok docs into subpages and sub navigation

f9f3d33

cleanup

5a6b363

dominic-retli-hashi marked this pull request as ready for review July 18, 2025 20:32

dominic-retli-hashi requested review from a team as code owners July 18, 2025 20:32

JarrettSpiker reviewed Jul 21, 2025

View reviewed changes

juliannatetreault reviewed Jul 21, 2025

View reviewed changes

dominic-retli-hashi and others added 9 commits July 22, 2025 11:24

Cleanup Docs

564e822

Co-authored-by: Julianna <[email protected]>

moved my additions that were in the incorrect directory to the correc…

9940926

…t directory

Changed "HYOK (Hold Your Own Key) to "Hold Your Own Key (HYOK)" for c…

367be54

…larity Co-authored-by: Julianna <[email protected]>

Added missing pipes in doc tables

e7f4c78

Co-authored-by: Julianna <[email protected]>

more cleanup/missing pipes

2313844

More awesome cleanup

cdd1fe1

Co-authored-by: Julianna <[email protected]>

More Cleanup

d1cf398

Co-authored-by: Julianna <[email protected]>

rewording

793416e

Merge branch 'dominicretli/TF-26977/hyok-api-documentation' of github…

5c74667

….com:hashicorp/web-unified-docs into dominicretli/TF-26977/hyok-api-documentation

JarrettSpiker reviewed Jul 23, 2025

View reviewed changes

		[JSON API error object]: https://jsonapi.org/format/#error-objects

		# AWS OIDC Configuration API reference



	Hold Your Own Key (HYOK) is only available on the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform. This includes the management of OIDC configurations.

		[JSON API error object]: https://jsonapi.org/format/#error-objects

		# Azure OIDC Configuration API reference

		[JSON API error object]: https://jsonapi.org/format/#error-objects

		# GCP OIDC Configuration API reference

	\| `hyok-encrypted-data-key` \| A reference to the HYOK encrypted data key used to secure this state version. \|
	\| `hyok-encrypted-data-key` \| A reference to the HYOK encrypted data key used to secure this state version. HCP Terraform only, requires the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform.) \|

	\| `data.attributes.hyok-enabled` \| boolean \| `false` \| Whether this workspace will secure HCP Terraform artifacts using Hold Your Own Key (HYOK) encryption. Once enabled, this can not be disabled. \|
	\| `data.attributes.hyok-enabled` \| boolean \| `false` \| Whether this workspace will secure HCP Terraform artifacts using Hold Your Own Key (HYOK) encryption. Once enabled, this can not be disabled. HCP Terraform only, requires the [HCP Terraform Premium plan](https://www.hashicorp.com/en/pricing?tab=terraform.) \|

-| `data.type`                      | string  |           | Must be `"azure-oidc-configurations"`.                                                                                                                                                                               |
+| `data.type`                      | string  |           | Must be `"azure-oidc-configurations"`. |
+| `data.attributes.client-id`                      | string  |           | The Client (or Application) ID of your Entra ID application. |
+| `data.attributes.subscription-id`           | string  |          | The ID of your Azure subscription. |
+| `data.attributes.client-id`                      | string  |           | The Tenant (or Directory) ID of your Entra ID application. |

-| `data.type`                      | string  |           | Must be `"gcp-oidc-configurations"`.                                                                                                                                                                               |
+| `data.type`                      | string  |           | Must be `"gcp-oidc-configurations"`. |
+| `data.attributes.service-account-email`                      | string  |           | The email of your GCP service account, with permissions to encrypt and decrypt using a Cloud KMS key. |
+| `data.attributes.workload-provider-name`                      | string  |           | The fully qualifies workload provider path. This should be in the format `projects/{project_number}/locations/global/workloadIdentityPools/{workload_identity_pool_id}/providers/{workload_identity_pool_provider_id}`|
+| `data.attributes.project-number`                      | string  |           | The  GCP Project containing the workload provider and service account. |

-| `data.type`                      | string  |           | Must be `"vault-oidc-configurations"`.                                                                                                                                                                    |
+| `data.type`                      | string  |           | Must be `"vault-oidc-configurations"`.   |
+| `data.attributes.address`                      | string  |           | The full address of your Vault instance.  |
+| `data.attributes.role `                      | string  |           | The name of a role in your Vault JWT auth path, with permission to encrypt and decrypt with a Transit secrets engine key  |
+| `data.attributes.namespace `                      | string  |           | The namespace your JWT auth path is mounted in. |
+| `data.attributes.auth-path `                      | string  |           | The mounting path of  JWT auth path of JWT auth. Defaults to `"jwt"` |
+| `data.attributes.encoded-cacert `                      | string  |           | (Optional) A base64 encoded certificate which can be used to authenticate your Vault certificate. Only needed for self-hosted Vault Enterprise instances with a self-signed certificate. |

Hold Your Own Key (HYOK) API Documentation #588

Are you sure you want to change the base?

Hold Your Own Key (HYOK) API Documentation #588

Uh oh!

Conversation

dominic-retli-hashi commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hashicorp-cla-app bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vercel Previews Deployed

Uh oh!

github-actions bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Broken Link Checker

Summary

Errors per input

Errors in content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliannatetreault left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dominic-retli-hashi commented Jul 17, 2025 •

edited

Loading

hashicorp-cla-app bot commented Jul 17, 2025 •

edited

Loading

github-actions bot commented Jul 17, 2025 •

edited

Loading

github-actions bot commented Jul 17, 2025 •

edited

Loading