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.

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

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

Method	Path
`GET`	`/terraform/config`

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/"
  }

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.

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

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

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

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

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.

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

$ 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

$ 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

$ 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
}