Skip to content

Add documentation for new organization level user-token-enabled setting #952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+36 −5
Open

Add documentation for new organization level user-token-enabled setting #952

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4f66230
docs: organization API
emlanctot Aug 22, 2025
602dca3
docs: cloud docs for user token disablement
emlanctot Aug 25, 2025
010af1c
docs: fix typos and add specificity
emlanctot Aug 25, 2025
75a269f
Apply suggestions from code review
emlanctot Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions content/terraform-docs-common/docs/cloud-docs/api-docs/organizations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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 an organization's resources through the API. Defaults to `true`. |

### Sample Payload

Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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 an organization's resources through the API. Defaults to `true`. |

### Sample Payload

Expand Down Expand Up @@ -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": {
Expand Down
20 changes: 20 additions & 0 deletions .../terraform-docs-common/docs/cloud-docs/users-teams-organizations/api-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,26 @@ 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.

### Disable user tokens 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.

If your organization has automations that authenticate using user tokens, disabling user tokens can cause those automations to fail.

<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

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.
Expand Down
4 changes: 4 additions & 0 deletions content/terraform-docs-common/docs/cloud-docs/users-teams-organizations/users.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 refer to [User API tokens](/terraform/cloud-docs/users-teams-organizations/api-tokens#user-api-tokens).

### 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.
Expand Down
Loading