HCP Terraform API documentation

HCP Terraform provides an API for a subset of its features. If you need assistance or want to submit a feature request, visit theHashiCorp support center and open a ticket.

HashiCorp provides astability policy for the HCP Terraform API, ensuring backwards compatibility for stable endpoints. Thechangelog tracks changes to the API for HCP Terraform and Terraform Enterprise.

Authentication

All requests must be authenticated with a bearer token. Use the HTTP headerAuthorization with the valueBearer <token>. If the token is absent or invalid, HCP Terraform responds withHTTP status 401 and aJSON API error object. The 401 status code is reserved for problems with the authentication token; forbidden requests with a valid token result in a 404.

You can use the following types of tokens to authenticate:

• User tokens — each HCP Terraform user can have any number of API tokens, which can make requests on their behalf.
• Team tokens — each team can have one API token at a time. This is intended for performing plans and applies via a CI/CD pipeline.
• Organization tokens — each organization can have one API token at a time. This is intended for automating the management of teams, team membership, and workspaces. The organization token cannot perform plans and applies.

Blob Storage Authentication

HCP Terraform relies on a HashiCorp-developed blob storage service for storing statefiles and multiple other pieces of customer data, all of which are documented on ourdata security page.

Unlike the HCP Terraform API, this service does not require that a bearer token be submitted with each request. Instead, each URL includes a securely generated secret and is only valid for 25 hours.

For example, thestate versions api returns a field namedhosted-state-download, which is a URL of this form:https://archivist.terraform.io/v1/object/<secret value>

This is a broadly accepted pattern for secure access. It is important to treat these URLs themselves as secrets. They should not be logged, nor shared with untrusted parties.

Feature Entitlements

HCP Terraform is available at multiple pricing tiers (including free), which offer different feature sets.

Each organization has a set ofentitlements that corresponds to its pricing tier. These entitlements determine which HCP Terraform features the organization can use.

If an organization doesn't have the necessary entitlement to use a given feature, HCP Terraform returns a 404 error for API requests to any endpoints devoted to that feature.

Theshow entitlement set endpoint can return information about an organization's current entitlements, which is useful if your client needs to change its interface when a given feature isn't available.

The following entitlements are available:

• agents — Allows isolated, private or on-premises infrastructure to communicate with an organization in HCP Terraform. Affects theagent pools,agents, andagent tokens endpoints.
• configuration-designer — Allows an organization to use theConfiguration Designer.
• cost-estimation — Allows an organization to accesscost estimation.
• global-run-tasks — Allows an organization to applyrun tasks to every workspace. Affects therun tasks endpoints. This feature is currently in beta.
• module-tests-generation - Allows an organization to generate tests for private registry modules. This feature is currently in beta.
• operations — Allows an organization to perform runs within HCP Terraform. Affects theruns,plans, andapplies endpoints.
• policy-enforcement — Allows an organization to useSentinel. Affects thepolicies,policy sets, andpolicy checks endpoints.
• private-module-registry — Allows an organization to publish and use modules with theprivate module registry. Affects theregistry modules endpoints.
• private-policy-agents - Allows an organization to ensure that HTTP enabledSentinel and OPApolicies can communicate with isolated, private, or on-premises infrastructure.
• run-tasks — Allows an organization to userun tasks. Affects therun tasks endpoints.
• self-serve-billing — Allows an organization to pay via credit card using the in-app billing UI.
• sentinel -DEPRECATED Usepolicy-enforcement instead.
• state-storage — Allows an organization to store state versions in its workspaces, which enables local Terraform runs with HCP Terraform. Affects thestate versions endpoints.
• sso — Allows an organization to manage and authenticate users with single sign on.
• teams — Allows an organization to manage access to its workspaces withteams. Without this entitlement, an organization only has an owners team. Affects theteams,team members,team access, andteam tokens endpoints.
• user-limit — An integer value representing the maximum number of users allowed for the organization. If blank, there is no limit.
• vcs-integrations — Allows an organization toconnect with a VCS provider and link VCS repositories to workspaces. Affects theOAuth Clients, andOAuth Tokens endpoints, and determines whether thedata.attributes.vcs-repo property can be set forworkspaces.

Response Codes

This API returns standard HTTP response codes.

We return 404 Not Found codes for resources that a user doesn't have access to, as well as for resources that don't exist. This is to avoid telling a potential attacker that a given resource exists.

Versioning

The API documented in these pages is the second version of HCP Terraform's API, and resides under the/v2 prefix.

Future APIs will increment this version, leaving the/v1 API intact, though in the future we might deprecate certain features. In that case, we'll provide ample notice to migrate to the new API.

Paths

All V2 API endpoints use/api/v2 as a prefix unless otherwise specified.

For example, if the API endpoint documentation defines the path/runs then the full path is/api/v2/runs.

JSON API Formatting

The HCP Terraform endpoints use theJSON API specification, which specifies key aspects of the API. Most notably:

• HTTP error codes
• Error objects
• Document structure
• HTTP request/response headers

JSON API Documents

Since our API endpoints use the JSON API spec, most of them returnJSON API documents.

Endpoints that use the POST method also require a JSON API document as the request payload. A request object usually looks something like this:

{  "data": {    "type":"vars",    "attributes": {      "key":"some_key",      "value":"some_value",      "category":"terraform",      "hcl":false,      "sensitive":false    },    "relationships": {      "workspace": {        "data": {          "id":"ws-4j8p6jX1w33MiDC7",          "type":"workspaces"        }      }    }  }}

These objects always include a top-leveldata property, which:

• Must have atype property to indicate what type of API object you're interacting with.
• Often has anattributes property to specify attributes of the object you're creating or modifying.
• Sometimes has arelationships property to specify other objects that are linked to what you're working with.

In the documentation for each API method, we use dot notation to explain the structure of nested objects in the request. For example, the properties of the request object above are listed as follows:

We also always include a sample payload object, to show the document structure more visually.

Query Parameters

Although most of our API endpoints use the POST method and receive their parameters as a JSON object in the request payload, some of them use the GET method. These GET endpoints sometimes require URL query parameters, in the standard...path?key1=value1&key2=value2 format.

Since these parameters were originally designed as part of a JSON object, they sometimes have characters that must bepercent-encoded in a query parameter. For example,[ becomes%5B and] becomes%5D.

For more about URI structure and query strings, seethe specification (RFC 3986) orthe Wikipedia page on URIs.

Pagination

Most of the endpoints that return lists of objects support pagination. A client may pass the following query parameters to control pagination on supported endpoints:

Additional data is returned in thelinks andmeta top level attributes of the response.

{  "data": [...],  "links": {    "self": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "first": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",    "prev": null,    "next": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20",    "last": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20"  },  "meta": {    "pagination": {      "current-page": 1,      "prev-page": null,      "next-page": 2,      "total-pages": 2,      "total-count": 21    }  }}

Inclusion of Related Resources

Some of the API's GET endpoints can return additional information about nested resources by adding aninclude query parameter, whose value is a comma-separated list of resource types.

The related resource options are listed in each endpoint's documentation where available.

The related resources will appear in anincluded section of the response.

Example:

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request GET \  https://app.terraform.io/api/v2/teams/team-n8UQ6wfhyym25sMe?include=users

{  "data": {    "id": "team-n8UQ6wfhyym25sMe",    "type": "teams",    "attributes": {      "name": "owners",      "users-count": 1      ...    },    "relationships": {      "users": {        "data": [          {              "id": "user-62goNpx1ThQf689e",              "type": "users"          }        ]      } ...    }    ...  },  "included": [    {      "id": "user-62goNpx1ThQf689e",      "type": "users",      "attributes": {        "username": "hashibot"        ...      } ...    }  ]}

Rate Limiting

You can make up to 30 requests per second to the API as an authenticated or unauthenticated request. If you reach the rate limit then your access will be throttled and an error response will be returned. Some endpoints have lower rate limits to prevent abuse, including endpoints that poll Terraform for a list of runs and endpoints related to user authentication. The adjusted limits are unnoticeable under normal use. If you receive a rate-limited response, the limit is reflected in thex-ratelimit-limit header once triggered.

Authenticated requests are allocated to the user associated with the authentication token. This means that a user with multiple tokens will still be limited to 30 requests per second, additional tokens will not allow you to increase the requests per second permitted.

Unauthenticated requests are associated with the requesting IP address.

{  "errors": [    {      "detail": "You have exceeded the API's rate limit.",      "status": 429,      "title": "Too many requests"    }  ]}

Client libraries and tools

HashiCorp maintainsgo-tfe, a Go client for HCP Terraform's API.

Additionally, the community of HCP Terraform users and vendors have built client libraries in other languages. These client libraries and tools are not tested nor officially maintained by HashiCorp, but are listed below in order to help users find them easily.

If you have built a client library and would like to add it to this community list, pleasecontribute tothis page.

• tfh: UNIX shell console app
• tf_api_gateway: Python API library and console app
• terrasnek: Python API library
• terraform-enterprise-client: Ruby API library and console app
• pyterprise: A simple Python API client library.
• Tfe.NetClient: .NET Client Library