Update HCP Terraform Secrets Engine docs to clarify API token types, scope limitations, and usage examples

[kevin-loehfelm]

This update revises the HCP Terraform Secrets Engine documentation to:

• Clearly explain the scope limitations of root/anchor credentials (user, team, org tokens).
• Emphasize that user tokens can only manage that user’s own resources.
• Provide guidance for selecting the appropriate token type for intended workflows.
• Expand examples for organization, team, legacy team, and user roles, including token lifecycle management and revocation behavior.
• Clarify that multiple engine mounts may be required to manage tokens for multiple users.

These changes improve accuracy and help prevent misconfiguration in real-world Vault deployments.

[kevin-loehfelm]

resolves #1267

[github-actions]

Vercel Previews Deployed

Name	Status	Preview	Updated (UTC)
Dev Portal	✅ Ready (Inspect)	Visit Preview	Sun Nov 9 01:34:32 UTC 2025
Unified Docs API	✅ Ready (Inspect)	Visit Preview	Sun Nov 9 01:27:45 UTC 2025

[github-actions]

Broken Link Checker

No broken links found! 🎉

[schavis]

Suggested change

	to determine the appropriate API token for use with the secret engine.
	to determine the appropriate API token for Terraform plugin.

[schavis]

Suggested change

	Vault issues dynamic Team API tokens by mapping a role to an existing HCP Terraform
	team. Vault manages these tokens’ lifecycle and automatically expires them according
	to the role’s `ttl` and `max_ttl`.
	Vault issues dynamic API tokens by mapping the Terrafrom role to an existing
	HCP Terraform team. Vault also manages the API token lifecycle and
	automatically expires the token according to the `ttl` and `max_ttl`
	settings on the role.

Style correction: avoid possessives, reserve capitalization for product names

[schavis]

Suggested change

	You will need to know the Team ID in order to generate Team API tokens for that team. You
	can use the HCP Terraform Teams API to find the desired Team ID. To find the Team ID, use the
	[HCP Terraform Teams API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/teams)
	or navigate to the Teams section in the HCP Terraform UI. Similarly, to find a User ID, use the
	[Account Details API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/account#show-the-current-user)
	or check your user profile in the UI.
	You need to know your Terraform team ID or user ID to generate API tokens
	for that client:
	- To find your team ID, use the
	[HCP Terraform Teams API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/teams)
	or navigate to the **Teams** section in the HCP Terraform GUI.
	- To find a user ID, use the
	[Account Details API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/account#show-the-current-user)
	or check your user profile in the HCP Terraform GUI.

Style correction: write in active voice, reserve capitalization for product/endpoint names

[schavis]

Suggested change

	Generate a new token by reading from the `/creds` endpoint with the role name:
	Generate a new token by calling the `/creds` endpoint with the role name:

[schavis]

Suggested change

	~> **IMPORTANT:** When selecting an anchor credential for the Terraform Secrets
	Engine, choose a token whose scope matches your intended use case. For example, a
	user token can only manage that user’s own resources, while a team token can manage
	team-level resources or other teams’ tokens if the appropriate permissions are granted.
	Using a token that is too narrowly scoped may prevent Vault from issuing tokens for your
	intended workflows.
	When you select an anchor credential for the Terraform plugin, always choose a
	token with a scope that matches your intended use case.
	User tokens should only have permission to manage the resources owned by that
	user. Team tokens should only have permission to manage team-level resources
	owned by that team. Only create tokens with cross-team permissions when a more
	narrowly-defined scope prevents Vault from issuing appropriate tokens or
	interferes with your intended workflows.

Style correction: write in active voice, provide explicit guidance whenever possible, avoid unnecessary callouts (warnings, tips, etc.)

[schavis]

Suggested change

	Traditionally, Vault secrets engines create dynamic users and credentials for those users.
	At this time, the HCP Terraform API does not support creating dynamic users. Instead, the
	HCP Terraform secrets engine issues dynamic User API tokens by configuring a Vault role to
	manage an existing HCP Terraform user.
	Vault manages the lifecycle of these tokens and automatically expires them based on the
	role’s configured `ttl` and `max_ttl`. Keep in mind that User API tokens are scoped to the
	individual user account — they cannot create or manage tokens for other users. If you need
	Vault to issue tokens that operate across teams or support automation workflows, use a team
	API token instead.
	Traditionally, Vault secrets engines create dynamic users and credentials for those users.
	The HCP Terraform API does not support creating dynamic users so the Terraform
	plugin issues dynamic User API tokens by configuring Vault roles to manage
	existing HCP Terraform users.
	Vault manages the lifecycle of user tokens and automatically expires them based
	on the `ttl` and `max_ttl` values of the role. Vault scopes User API tokens to
	the individual user account. As a result, the associated account cannot create
	or manage tokens for other users. Use a team API token if you need Vault to
	issue tokens that operate across teams or support automation workflows.

Style correction: avoid cross-sentence pronouns, avoid em dashes, avoid possessives

[schavis]

Suggested change

	Below is an example of creating a Vault role to manage User API tokens:
	The `terraform/role/{user}` endpoint can create a Vault role to manage User API tokens. For example:

[schavis]

Suggested change

	which will ensure the token expires at the `max_ttl` time. This prevents
	which ensures that the token expires at the `max_ttl` time and prevents

Style correction: write in active voice, avoid "this" as a pronoun

[schavis]

Suggested change

	It is highly recommended you set an additional description.
	We highly recommended setting an additional description.

Style correction: write in active voice

[schavis]

Suggested change

	Below is an example of creating a Vault role to manage Team API tokens:
	For example, to set a description when you create a Vault role to manage Team API tokens, use the `description` parameter: