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

# 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](/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 three distinct types of API tokens with varying level of
access: Organizations, Teams, 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
- To manage a User API token, provide a `user_id` parameter

~> **Special Note:** both Organizations and Teams can only have a single active API
token at any given time. Generating a new token for a team or organization will
effectively revoke any existing tokens, regardless if those tokens were
originally created by Vault. As such, requesting an Organization or 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](https://www.terraform.io/docs/cloud/users-teams-organizations/api-tokens.html).

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

- `ttl` `(duration: "")` – Specifies the TTL for this role. If not
  provided, the default Vault TTL is used. Only applies to User API tokens.
  Uses [duration format strings](/docs/concepts/duration-format).

- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not
  provided, the default Vault Max TTL is used. Only applies to User API tokens.
  Uses [duration format strings](/docs/concepts/duration-format).

### Sample Payload

To create a Vault role to manage a Terraform Cloud User tokens

```json
{
  "user_id": "user-glhf1234",
  "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": {
    "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 Team. This endpoint is only valid for those roles; attempting to
rotate a role that manages user 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 Team roles, the same API token is returned
until the token is rotated with `rotate-role`. For User 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
}
```