Terraform Cloud secret backend HTTP API

This is the API documentation for the Vault Terraform Cloud secret backend. For general information about the usage and operation of the Terraform Cloud backend, please see the Vault Terraform Cloud backend documentation.

This documentation assumes the Terraform Cloud backend is mounted at the /terraform path in Vault. Since it is possible to mount secret backends at any location, please update your API calls accordingly.

Configure access

This endpoint configures the access information for Terraform Cloud. This access information is used so that Vault can communicate with Terraform Cloud and generate Terraform Cloud tokens.

Parameters

• address (string: "") – Specifies the address of the Terraform Cloud server, if using Terraform Enterprise, provided as "protocol://host:port". The default is https://app.terraform.io for Terraform Cloud.

• token (string: "") – Specifies the Terraform Cloud authentication token to use. This token must have the needed permissions to manage all Organization, Team, and User tokens desired for this mount.

• explicit_max_ttl (integer: 0) – Specifies the maximum lifetime, in seconds, set on the root token in Terraform Cloud or Enterprise when Vault rotates it. Acts as an upper-bound safety net; Vault manages the root token lifecycle. The default (0) omits the expiration, so Terraform Cloud or Enterprise applies its default token lifetime of two years from the time of creation. The same value applies to both manual and automatic rotation. Refer to the Terraform token API documentation for organization, team, and user tokens for details on the default expiration.

• rotation_period (string/integer: 0) –
  Enterprise
  The amount of time, in seconds, Vault should wait before rotating the root credential. A zero value tells Vault not to rotate the root credential. The minimum rotation period is 10 seconds. You must set one of rotation_period or rotation_schedule, but cannot set both.
• rotation_schedule (string: "") –
  Enterprise
  The schedule, in cron-style time format, defining the schedule on which Vault should rotate the root credential. Standard cron-style time format uses five fields to define the minute, hour, day of month, month, and day of week respectively. For example, 0 0 * * SAT tells Vault to rotate the root credential every Saturday at 00:00. In 1.20.5 or later, Vault interprets the schedule in UTC. You must set one of rotation_schedule or rotation_period, but cannot set both.
• rotation_window (string/integer: 0) –
  Enterprise
  The maximum amount of time, in seconds, allowed to complete a rotation when a scheduled credential rotation occurs. If Vault cannot rotate the credential within the window (for example, due to a failure), Vault must wait to try again until the next scheduled rotation. The default rotation window is unbound and the minimum allowable window is 1 hour. You cannot set a rotation window when using rotation_period.
• disable_automated_rotation (bool: false) -
  Enterprise
  Cancels all upcoming rotations of the root credential until unset.

Sample payload

{
  "address": "https://app.terraform.io",
  "token": "glhf..."
}

Sample request

$ curl \
    --request POST \
    --header "X-Vault-Token: ..." \
    --data @payload.json \
    http://127.0.0.1:8200/v1/terraform/config

Read access configuration

This endpoint queries for information about the Terraform Cloud connection.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/terraform/config

Sample response

{
  "data": {
    "address": "https://app.terraform.io",
    "base_path": "/api/v2/",
    "explicit_max_ttl": 0,
    "token_owner_type": "user",
    "owner_id": "user-glhf1234",
    "rotation_period": 0,
    "rotation_schedule": "0 0 * * SAT",
    "rotation_window": 3600,
    "disable_automated_rotation": false,
    "last_vault_rotation": "2026-04-04T00:00:00Z",
    "next_vault_rotation": "2026-04-11T00:00:00Z"
  }
}

The token_owner_type and owner_id fields describe the root token Vault manages. Vault discovers them from Terraform Cloud or Enterprise the first time it rotates the token, so they remain empty until the first rotation. Vault includes the last_vault_rotation and next_vault_rotation fields only after a rotation occurs or you configure a rotation schedule.

Rotate root token

This endpoint rotates the configured root token that Vault uses to authenticate with Terraform Cloud or Enterprise. Vault creates a new token of the same type (organization, team, or user), validates it, stores it as the new root token, and revokes the previous token where Terraform supports revocation.

Use this endpoint for on-demand rotation. It does not require Vault Enterprise. Configure scheduled, automatic rotation with the rotation fields on the /terraform/config endpoint, which requires Vault Enterprise.

To revoke the previous token during rotation, Vault must know its token ID. On HCP Terraform and Terraform Enterprise v2.1 and later, Vault discovers the token ID automatically from the auth-token link in the /account/details response, so it revokes the previous team or user token on every rotation.

On earlier versions of Terraform Enterprise that do not return the auth-token link, Vault cannot determine the ID of the initially-configured token. The first time Vault rotates a team or user token, it returns a warning asking you to revoke that initial token manually in Terraform. Vault records the ID of each token it creates, so subsequent rotations revoke the previous token automatically.

For organization tokens, Terraform implicitly replaces the token when Vault creates a new one, so Vault performs no explicit revocation.

Parameters

There are no parameters to this operation.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/terraform/rotate-root

Sample response

{
  "data": {
    "token_owner_type": "user",
    "owner_id": "user-glhf1234",
    "last_vault_rotation": "2026-04-02T23:30:00Z"
  }
}

Create/Update role

This endpoint creates or updates the Terraform Cloud role definition in Vault. If the role does not exist, it will be created. If the role already exists, it will receive updated attributes.

Terraform Cloud offers four distinct types of API tokens with varying level of access: Organizations, Teams, Legacy Teams (deprecated in HCP Terraform) and Users. A Vault Role can manage a single type of API token at a time, determined by how it is configured:

• To manage an Organization API token, provide the organization name with the organization parameter
• To manage a Team API token, provide the team_id parameter and set the credential_type parameter to team
• To manage a Legacy Team API token, provide the team_id parameter and set the credential_type parameter to team_legacy
• To manage a User API token, provide a user_id parameter

Please see the Terraform Cloud API Token documentation for more information.

Parameters

• name (string: <required>) – Specifies the name for the Vault role. This is part of the request URL.

• organization (string: "") – Organization name to manage the single API token. Organizations can only have a single active API token at any given time. Conflicts with user_id.

• team_id (string: "") – Team ID to manage the single API token. Teams can only have a single active API token at any given time. Conflicts with user_id.

• user_id (string: "") – User ID to manage dynamic tokens. Conflicts with organization and team_id.

• credential_type (string: "") – Specifies the type of credential to generate. If unspecified, Vault sets it automatically based on the type of id (defaults to team_legacy if setting team_id). Valid values are team, team_legacy, user, or organization.

• description (string: "") - Description of the role. Applies to User and Team API tokens. Used as a prefix to help identify the token in the HCP Terraform UI.

• ttl (duration: "") – Specifies the TTL for this role. If not provided, the default Vault TTL is used. Applies to User and Team API tokens. Uses duration format strings.

• max_ttl (duration: "") – Specifies the max TTL for this role. If not provided, the default Vault Max TTL is used. Applies to User and Team API tokens. Uses duration format strings.

Sample payload

To create a Vault role to manage Terraform Cloud User tokens

{
  "user_id": "user-glhf1234",
  "credential_type": "user",
  "description": "description",
  "ttl": "1h",
  "max_ttl": "24h"
}

Sample request

$ curl \
    --request POST \
    --header "X-Vault-Token: ..." \
    --data @payload.json \
    http://127.0.0.1:8200/v1/terraform/role/tfuser

Read role

This endpoint queries for information about a Terraform Cloud role with the given name. If no role exists with that name, a 404 is returned.

Parameters

• name (string: <required>) – Specifies the name of the role to query. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/terraform/role/tfuser

Sample response

{
  "data": {
    "credential_type": "user",
    "description": "description",
    "max_ttl": 86400,
    "name": "tfuser",
    "ttl": 3600,
    "user_id": "user-glhf1234"
  }
}

List roles

This endpoint lists all existing roles in the backend.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/terraform/role

Sample response

{
  "data": {
    "keys": ["tfuser"]
  }
}

Delete role

This endpoint deletes a Terraform Cloud role with the given name. Even if the role does not exist, this endpoint will still return a successful response.

Parameters

• name (string: <required>) – Specifies the name of the role to delete. This is part of the request URL.

Sample request

$ curl \
    --request DELETE \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/terraform/role/tfuser

Rotate role

This endpoint rotates the credentials for a Terraform Cloud role that manages an Organization or Legacy Team. This endpoint is only valid for those roles; attempting to rotate a role that manages User or Team tokens will result in an error.

Parameters

• name (string: <required>) – Specifies the name of the role to rotate. This is part of the request URL.

Sample request

$ curl \
    --request POST \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/terraform/rotate-role/testing

Generate credential

This endpoint returns a Terraform Cloud token based on the given role definition. For Organization and Legacy Team roles, the same API token is returned until the token is rotated with rotate-role. For User and Team roles, a new token is generated with each request.

Parameters

• name (string: <required>) – Specifies the name of an existing role against which to create this Terraform Cloud token. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/terraform/creds/example

Sample response

{
  "request_id": "71629848-778d-f9ae-c396-0b02fae2adda",
  "lease_id": "terraform/creds/tfuser/dWa2E5aiIX7jJfyMqPm1fSPr",
  "lease_duration": 60,
  "renewable": true,
  "data": {
    "token": "<example-token>",
    "token_id": "at-example"
  },
  "warnings": null
}