HCP Terraform secrets engine

The HCP Terraform secrets engine for Vault generates HCP Terraform API tokens dynamically for Organizations, Teams, and Users.

This page will show a quick start for this backend. For detailed documentation on every path, use vault path-help after mounting the backend.

Terraform Enterprise Support: this secret engine supports both Terraform Cloud (app.terraform.io) as well as on-prem Terraform Enterprise. Any version requirements will be documented alongside the features that require them, if any.

Quick start

Most secrets engines must be configured in advance before they can perform their functions. An operator or configuration management tool usually completes these steps.

Enable the HCP Terraform secrets engine:
```
$ vault secrets enable terraform
Success! Enabled the terraform secrets engine at: terraform/
```
By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the -path argument.
Configure Vault to connect and authenticate to HCP Terraform:
```
$ vault write terraform/config \
    token=<user | team | org token>
Success! Data written to: terraform/config
```
Specify the address parameter when configuring Terraform Enterprise to override the default https://app.terraform.io:
```
$ vault write terraform/config \
    address="https://tfe.example.com" \
    token=<user | team | org token>
Success! Data written to: terraform/config
```
See HCP Terraform's documentation on API tokens to determine the appropriate API token for use with the Terraform plugin. Choose a token that matches your intended scope. See Organization, legacy team, team, and user roles section for additional considerations.

Configure a role for an HCP Terraform Team

Vault issues dynamic API tokens by mapping the Terraform secret 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 setting on the role.

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.

$ vault write terraform/role/my-team-role \
    team_id=team-12345abcde \
    credential_type=team \
    description="CI/CD automation token" \
    ttl=300 \
    max_ttl=1800
Success! Data written to: terraform/role/my-team-role

Usage

After the secrets engine is configured, a Vault token with the proper permissions can generate short-lived Team API tokens.

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

$ vault read terraform/creds/my-team-role
Key                Value
---                -----
lease_id           terraform/creds/my-team-role/A_LEASE_ID_abc123
lease_duration     300s
lease_renewable    true
token              tftk.abcdef1234567890
token_id           at-456defghi789
description        CI/CD automation token(42)
expired_at         2025-11-08T21:30:00Z

Organization, legacy team, team, and user roles

HCP Terraform supports four distinct types of API tokens; Organizations, Teams, Legacy Team Tokens and Users. Each token type has distinct access levels and generation workflows. A given Vault role can manage any one of the supported types at a time, however there are important differences to be aware of.

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.

Organization roles

Generating a new Organization API token by reading the credentials in Vault or otherwise generating them on app.terraform.io will effectively revoke any existing API token for that Organization.

Due to this behavior, Organization API tokens created by Vault will be stored and returned on future requests, until the credentials get rotated. This is to prevent unintentional revocation of tokens that are currently in-use.

Below is an example of creating a Vault role to manage an Organization API token and rotating the token:

$ vault write terraform/role/testing \
    organization="${TF_ORGANIZATION}" \
    credential_type=organization
Success! Data written to: terraform/role/testing

$ vault write -f terraform/rotate-role/testing
Success! Data written to: terraform/rotate-role/testing

The API token is retrieved by reading the credentials for the role:

$ vault read terraform/creds/testing

Key             Value
---             -----
organization    hashicorp-vault-testing
role            testing
token           <example token>
token_id        at-fqvtdTQ5kQWcjUfG

User roles

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.

The terraform/role/{user} endpoint can create a Vault role to manage User API tokens. For example:

$ vault write terraform/role/user-testing \
    user_id="${TF_USER_ID}"
Success! Data written to: terraform/role/user-testing

Retrieve the API token by reading the credentials for the role:

$ vault read terraform/creds/user-testing

Key             Value
---             -----
role            user-testing
token           <example token>
token_id        at-fqvtdTQ5kQWcjUfG

Team roles

The HCP Terraform secret engine creates dynamic Team API tokens by configuring a Vault role to manage an existing HCP Terraform Team. The lifecycle of these tokens is managed by Vault and/or HCP Terraform. Generally, Vault aims to manage tokens in external APIs with revoke actions taken according to ttl and max_ttl settings. In addition to that behavior, using the max_ttl Vault will set an ExpiredAt date in HCP Terraform which ensures that the token expires at the max_ttl time and prevents Team tokens living past their max_ttl if Vault is unable to revoke the token. Omitting the max_ttl value will default to Vault's system max_ttl.

In HCP Terraform, team tokens cannot have matching descriptions. In order to avoid collisions, the secret engine generates a random string as a suffix to the description. We highly recommended setting an additional description.

For example, to set a description when you create a Vault role to manage Team API tokens, use the description parameter:

$ vault write terraform/role/team-testing \
    team_id="${TF_TEAM_ID}" \
    credential_type=team \
    description="testing token" \
    ttl=200 \
    max_ttl=600
Success! Data written to: terraform/role/team-testing

The API token is retrieved by reading the credentials for the role:

$ vault read terraform/creds/team-testing

Key             Value
---             -----
lease_id           terraform/creds/team-testing/4oNxB4X0x77IrP51lBMJBiJi
lease_duration     3m20s
lease_renewable    true
description        testing token(74)
expired_at         2025-05-01T20:10:55Z
token              <example token>
token_id           at-GDMeMTvn3NhUernt

Legacy team roles (Deprecated)

The HCP Terraform API limits Legacy Team roles to one active token at any given time. Generating a new Legacy Team API token by reading the credentials in Vault or otherwise generating them on app.terraform.io will effectively revoke any existing API token for that Team.

Due to this behavior, Legacy Team API tokens created by Vault will be stored and returned on future requests, until the credentials get rotated. This is to prevent unintentional revocation of tokens that are currently in-use.

Below is an example of creating a Vault role to manage a Legacy Team API token and rotating the token:

$ vault write terraform/role/legacy-team \
    team_id="${TF_TEAM_ID}" \
    credential_type=team_legacy
Success! Data written to: terraform/role/legacy-team

$ vault write -f terraform/rotate-role/legacy-team
Success! Data written to: terraform/rotate-role/legacy-team

The API token is retrieved by reading the credentials for the role:

$ vault read terraform/creds/legacy-team

Key             Value
---             -----
organization    n/a
role            legacy-team
team_id         team-<id>
token           <example token>
token_id        at-fqvtdTQ5kQWcjUfG