Apply suggestions from code review

emlanctot · rkoron007 · helenjw · commit c70957b57471 · 2025-09-16T09:18:07.000-04:00
Co-authored-by: Rose M Koron &lt;32436232+rkoron007@users.noreply.github.com&gt;
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
@@ -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
@@ -16,20 +16,25 @@ 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.
 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. 
+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.
+<Note>
+
+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.
+
+</Note>
 
 ## 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
@@ -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
 
