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

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. This is provided as a string duration with a time suffix like "30s" or "1h" or as seconds. If not provided, the default Vault TTL is used. Only applies to User API tokens.
max_ttl (duration: "") – Specifies the max TTL for this role. This is provided as a string duration with a time suffix like "30s" or "1h" or as seconds. If not provided, the default Vault Max TTL is used. Only applies to User API tokens.

Sample payload

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

{
  "user_id": "user-glhf1234",
  "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": {
    "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 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

$ 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

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