vault/website/content/api-docs/secret/terraform.mdx

---
layout: api
page_title: Terraform Cloud Secret Backend - HTTP API
description: This is the API documentation for the Vault Terraform Cloud secret backend.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# 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](/vault/docs/secrets/terraform).

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.

| Method | Path                |
| :----- | :------------------ |
| `POST` | `/terraform/config` |

### 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.

### Sample payload

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

### Sample request

```shell-session
$ 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.

| Method | Path                |
| :----- | :------------------ |
| `GET`  | `/terraform/config` |

### Sample request

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

### Sample response

```json
  "data": {
    "address": "https://app.terraform.io",
    "base_path": "/api/v2/"
  }
```

## 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

~> **Special Note:** Organizations and Legacy Teams can only have a single active API
token at any given time. Generating a new token for an organization or legacy team will
effectively revoke any existing tokens, regardless if those tokens were
originally created by Vault. As such, requesting an Organization or Legacy Team token
from Vault will return the same token indefinitely until that token is rotated
with the `/rotate-role` endpoint.

Please see the [Terraform Cloud API
Token documentation for more
information](/terraform/cloud-docs/users-teams-organizations/api-tokens).

| Method | Path                    |
| :----- | :---------------------- |
| `POST` | `/terraform/role/:name` |

### 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](/vault/docs/concepts/duration-format).

- `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](/vault/docs/concepts/duration-format).

### Sample payload

To create a Vault role to manage Terraform Cloud User tokens

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

### Sample request

```shell-session
$ 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.

| Method | Path                    |
| :----- | :---------------------- |
| `GET`  | `/terraform/role/:name` |

### Parameters

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

### Sample request

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

### Sample response

```json
{
  "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.

| Method | Path                        |
| :----- | :-------------------------- |
| `LIST` | `/terraform/role`           |
| `GET`  | `/terraform/role?list=true` |

### Sample request

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

### Sample response

```json
{
  "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.

| Method   | Path                    |
| :------- | :---------------------- |
| `DELETE` | `/terraform/role/:name` |

### Parameters

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

### Sample request

```shell-session
$ 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.

| Method | Path                           |
| :----- | :----------------------------- |
| `POST` | `/terraform/rotate-role/:name` |

### Parameters

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

### Sample request

```shell-session
$ 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.

| Method | Path                     |
| :----- | :----------------------- |
| `GET`  | `/terraform/creds/:name` |

### 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

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

### Sample response

```json
{
  "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
}
```