From 4f66230c3be814953bdc857bebc2b7092429276a Mon Sep 17 00:00:00 2001 From: emlanctot Date: Fri, 22 Aug 2025 15:25:52 -0700 Subject: [PATCH 1/4] docs: organization API --- .../docs/cloud-docs/api-docs/organizations.mdx | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx index 833f351b4c..dd99ed94bc 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx @@ -134,7 +134,8 @@ curl \ "owners-team-saml-role-id": null, "two-factor-conformant": false, "assessments-enforced": false, - "default-execution-mode": "remote" + "default-execution-mode": "remote", + "user-tokens-enabled: true }, "relationships": { "default-agent-pool": { @@ -223,7 +224,8 @@ curl \ "owners-team-saml-role-id": null, "two-factor-conformant": false, "assessments-enforced": false, - "default-execution-mode": "remote" + "default-execution-mode": "remote", + "user-tokens-enabled: true }, "relationships": { "default-agent-pool": { @@ -358,7 +360,8 @@ curl \ "owners-team-saml-role-id": null, "two-factor-conformant": false, "assessments-enforced": false, - "default-execution-mode": "remote" + "default-execution-mode": "remote", + "user-tokens-enabled: true }, "relationships": { "default-agent-pool": { @@ -430,6 +433,7 @@ Properties without a default value are required. | `data.attributes.default-execution-mode` | string | `remote` | Which [execution mode](/terraform/cloud-docs/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`. | | `data.attributes.enforce-hyok` | boolean | false | Whether or not new workspaces within the organization are created with hold your own key enabled. Your organization must have a primary HYOK configuration before enabling `enforce-hyok`. Hold your own key is only available in HCP Terraform, [learn more](/terraform/cloud-docs/hold-your-own-key). | +| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access organization resources through the API. Defaults to true. | ### Sample Payload @@ -512,7 +516,8 @@ curl \ "owners-team-saml-role-id": null, "two-factor-conformant": false, "assessments-enforced": false, - "default-execution-mode": "remote" + "default-execution-mode": "remote", + "user-tokens-enabled: true }, "relationships": { "default-agent-pool": { @@ -622,6 +627,7 @@ This PATCH endpoint requires a JSON object with the following properties as a re | `data.attributes.default-execution-mode` | string | `remote` | Which [execution mode](/terraform/cloud-docs/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`. | | `data.attributes.enforce-hyok` | boolean | false | Whether or not new workspaces within the organization are created with hold your own key (HYOK) enabled. Your organization must have a primary HYOK configuration before enabling `enforce-hyok`. Hold your own key is only available in HCP Terraform, [learn more](/terraform/cloud-docs/hold-your-own-key). | +| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access organization resources through the API. Defaults to true. | ### Sample Payload @@ -702,7 +708,8 @@ curl \ "owners-team-saml-role-id": null, "two-factor-conformant": false, "assessments-enforced": false, - "default-execution-mode": "remote" + "default-execution-mode": "remote", + "user-tokens-enabled: true }, "relationships": { "default-agent-pool": { From 602dca396766b91e08361ecc6297bb8393f47e06 Mon Sep 17 00:00:00 2001 From: emlanctot Date: Mon, 25 Aug 2025 13:10:16 -0700 Subject: [PATCH 2/4] docs: cloud docs for user token disablement --- .../users-teams-organizations/api-tokens.mdx | 15 +++++++++++++++ .../users-teams-organizations/users.mdx | 4 ++++ 2 files changed, 19 insertions(+) diff --git a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx index 1c50dd25e5..b09e368ded 100644 --- a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx @@ -16,6 +16,21 @@ Refer to [Team Token API](/terraform/cloud-docs/api-docs/team-tokens) and [Organ API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#tokens) documentation. +### Disabling user tokens for organizations + +When user tokens are disabled for an organization, all user tokens will be blocked from accessing organization resources. By default, user tokens are enabled for organizations. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, then navigate to the organization where you want to disable user tokens. +1. Choose **Settings** from the sidebar, then **API tokens**. +1. From the **User Tokens** tab, uncheck the **Allow members to access organization resources with their user tokens** setting. +1. Click **Update settings**. +1. In the confirmation modal, select **Disable**. +1. User tokens are now disabled for this organization. + +!> **Warning:** Use caution disabling user tokens for an organization. This could cause automation to fail if the automation is using user tokens to authenticate. + +-> **Note:** When user tokens are disabled for an organization, that organization should use `oauth-token-id` to configure their VCS connections rather than `github-app-installation-id`, as the latter relies on user tokens to authenticate to Github. + ## Team API Tokens API tokens may belong to a specific team. Team API tokens allow access to the workspaces that the team has access to, without being tied to any specific user. diff --git a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx index bf02019f51..284f4b09b6 100644 --- a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx @@ -191,6 +191,10 @@ To revoke a token, click the **trash can** next to it. That token will no longer ~> **Note**: HCP Terraform does not revoke a user API token's access to an organization when you remove the user from an SSO Identity Provider as the user may still be a member of the organization. To remove access to a user's API token, remove the user from the organization in the UI or with the [Terraform Enterprise provider](https://registry.terraform.io/providers/hashicorp/tfe/latest). +#### Tokens disabled + +User tokens can be disabled at the organization level, for more information see the [API token](/terraform/cloud-docs/users-teams-organizations/api-tokens#user-api-tokens) documentation. + ### GitHub app OAuth token Click **Tokens** in the sidebar to manage your GitHub App token. This token lets you connect a workspaces to an available GitHub App installation. From 010af1cda8ddf38852f165568590e9c5fdc6c582 Mon Sep 17 00:00:00 2001 From: emlanctot Date: Mon, 25 Aug 2025 13:54:01 -0700 Subject: [PATCH 3/4] docs: fix typos and add specificity --- .../docs/cloud-docs/api-docs/organizations.mdx | 10 +++++----- .../users-teams-organizations/api-tokens.mdx | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx index dd99ed94bc..f08a884ae1 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx @@ -135,7 +135,7 @@ curl \ "two-factor-conformant": false, "assessments-enforced": false, "default-execution-mode": "remote", - "user-tokens-enabled: true + "user-tokens-enabled": true }, "relationships": { "default-agent-pool": { @@ -225,7 +225,7 @@ curl \ "two-factor-conformant": false, "assessments-enforced": false, "default-execution-mode": "remote", - "user-tokens-enabled: true + "user-tokens-enabled": true }, "relationships": { "default-agent-pool": { @@ -361,7 +361,7 @@ curl \ "two-factor-conformant": false, "assessments-enforced": false, "default-execution-mode": "remote", - "user-tokens-enabled: true + "user-tokens-enabled": true }, "relationships": { "default-agent-pool": { @@ -517,7 +517,7 @@ curl \ "two-factor-conformant": false, "assessments-enforced": false, "default-execution-mode": "remote", - "user-tokens-enabled: true + "user-tokens-enabled": true }, "relationships": { "default-agent-pool": { @@ -709,7 +709,7 @@ curl \ "two-factor-conformant": false, "assessments-enforced": false, "default-execution-mode": "remote", - "user-tokens-enabled: true + "user-tokens-enabled": true }, "relationships": { "default-agent-pool": { diff --git a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx index b09e368ded..440022218b 100644 --- a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx @@ -18,7 +18,7 @@ API tokens may belong directly to a user. User tokens are the most flexible toke ### Disabling user tokens for organizations -When user tokens are disabled for an organization, all user tokens will be blocked from accessing organization resources. By default, user tokens are enabled for organizations. +When user tokens are disabled for an organization, all user tokens will be blocked from accessing organization resources on the API. By default, user tokens are enabled for organizations. 1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, then navigate to the organization where you want to disable user tokens. 1. Choose **Settings** from the sidebar, then **API tokens**. @@ -29,7 +29,7 @@ When user tokens are disabled for an organization, all user tokens will be block !> **Warning:** Use caution disabling user tokens for an organization. This could cause automation to fail if the automation is using user tokens to authenticate. --> **Note:** When user tokens are disabled for an organization, that organization should use `oauth-token-id` to configure their VCS connections rather than `github-app-installation-id`, as the latter relies on user tokens to authenticate to Github. +-> **Note:** When user tokens are disabled for an organization, that organization should use **Github (OAuth)** to configure their VCS connections rather than **Github (App)**, as the latter relies on user tokens to authenticate to Github. ## Team API Tokens From 75a269f3407572de244b94eac0fc1c7d7f6f6c5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emma=20Lanct=C3=B4t?= Date: Tue, 26 Aug 2025 12:13:54 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Rose M Koron <32436232+rkoron007@users.noreply.github.com> --- .../docs/cloud-docs/api-docs/organizations.mdx | 4 ++-- .../users-teams-organizations/api-tokens.mdx | 13 +++++++++---- .../cloud-docs/users-teams-organizations/users.mdx | 2 +- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx index f08a884ae1..8c25adcdfa 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx @@ -433,7 +433,7 @@ Properties without a default value are required. | `data.attributes.default-execution-mode` | string | `remote` | Which [execution mode](/terraform/cloud-docs/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`. | | `data.attributes.enforce-hyok` | boolean | false | Whether or not new workspaces within the organization are created with hold your own key enabled. Your organization must have a primary HYOK configuration before enabling `enforce-hyok`. Hold your own key is only available in HCP Terraform, [learn more](/terraform/cloud-docs/hold-your-own-key). | -| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access organization resources through the API. Defaults to true. | +| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access an organization's resources through the API. Defaults to `true`. | ### Sample Payload @@ -627,7 +627,7 @@ This PATCH endpoint requires a JSON object with the following properties as a re | `data.attributes.default-execution-mode` | string | `remote` | Which [execution mode](/terraform/cloud-docs/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`. | | `data.attributes.enforce-hyok` | boolean | false | Whether or not new workspaces within the organization are created with hold your own key (HYOK) enabled. Your organization must have a primary HYOK configuration before enabling `enforce-hyok`. Hold your own key is only available in HCP Terraform, [learn more](/terraform/cloud-docs/hold-your-own-key). | -| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access organization resources through the API. Defaults to true. | +| `data.attributes.user-tokens-enabled` | boolean | true | Whether or not user tokens can access an organization's resources through the API. Defaults to `true`. | ### Sample Payload diff --git a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx index 440022218b..f9001fa894 100644 --- a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx @@ -16,10 +16,11 @@ Refer to [Team Token API](/terraform/cloud-docs/api-docs/team-tokens) and [Organ API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/cloud-docs/users-teams-organizations/users#tokens) documentation. -### Disabling user tokens for organizations +### Disable user tokens for organizations -When user tokens are disabled for an organization, all user tokens will be blocked from accessing organization resources on the API. By default, user tokens are enabled for organizations. +By default, user tokens are enabled for organizations. When your organization disables user tokens, the HCP Terraform API blocks user tokens from accessing organization resources. +To disable user tokens for your organization, perform the following steps: 1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, then navigate to the organization where you want to disable user tokens. 1. Choose **Settings** from the sidebar, then **API tokens**. 1. From the **User Tokens** tab, uncheck the **Allow members to access organization resources with their user tokens** setting. @@ -27,9 +28,13 @@ When user tokens are disabled for an organization, all user tokens will be block 1. In the confirmation modal, select **Disable**. 1. User tokens are now disabled for this organization. -!> **Warning:** Use caution disabling user tokens for an organization. This could cause automation to fail if the automation is using user tokens to authenticate. +If your organization has automations that authenticate using user tokens, disabling user tokens can cause those automations to fail. --> **Note:** When user tokens are disabled for an organization, that organization should use **Github (OAuth)** to configure their VCS connections rather than **Github (App)**, as the latter relies on user tokens to authenticate to Github. + + +An organization that disables user tokens cannot connect to VCS using the [Github (App)](/terraform/cloud-docs/vcs/github-app), because it relies on user tokens to authenticate. Your organization can use [Github (OAuth) to configure their VCS connections](/terraform/cloud-docs/vcs/github) instead. + + ## Team API Tokens diff --git a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx index 284f4b09b6..5efdd40edd 100644 --- a/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx @@ -193,7 +193,7 @@ To revoke a token, click the **trash can** next to it. That token will no longer #### Tokens disabled -User tokens can be disabled at the organization level, for more information see the [API token](/terraform/cloud-docs/users-teams-organizations/api-tokens#user-api-tokens) documentation. +User tokens can be disabled at the organization level, for more information refer to [User API tokens](/terraform/cloud-docs/users-teams-organizations/api-tokens#user-api-tokens). ### GitHub app OAuth token