instruction: Explain terraform_official API usage with examples and best practices
output: API documentation overview
  HCP Terraform provides an API for a subset of its features. If you need assistance or want to submit a feature request, visit the 
  HashiCorp support center
   and open a ticket.
  Before planning an API integration, consider whether the 
  HCP Terraform and Terraform Enterprise provider
   meets your needs. It can't create or approve runs in response to arbitrary events, but it's a useful tool for managing your organizations, teams, and workspaces as code.
  The 
  HashiCorp API stability policy
   ensures backward compatibility for stable endpoints. The 
  changelog
   tracks changes to the API.
  Authentication
  All requests must be authenticated with a bearer token. Use the HTTP header 
  Authorization
   with the value 
  Bearer <token>
  . If the token is absent or invalid, HCP Terraform responds with 
  HTTP status 401
   and a 
  JSON 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.
  Audit trails token
   - each organization can have a single token that can read that organization's audit trails. Use this token type to authenticate integrations pulling audit trail data, for example, using the 
  HCP Terraform for Splunk
   app.
  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 our 
  data security page
  .
  This service does not require you to submit a bearer token with each request. Instead, each URL includes a securely-generated secret and is only valid for 25 hours.
  For example, the 
  state versions endpoint
   returns a field named 
  hosted-state-download
   that contains a URL in the following format:
  https://archivist.terraform.io/v1/object/<secret value>
  This is a widely accepted pattern for secure access. Treat URLs retrieved from the blob storage service as secrets. Do not log them or share them 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 of 
  entitlements
   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, the application returns a 
  404
   error for API requests to any endpoints devoted to that feature.
  The 
  show 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 the 
  agent pools
  , 
  agents
  , and 
  agent tokens
   endpoints.
  audit-logging
   — Allows an organization to access 
  audit trails
  .
  configuration-designer
   — Allows an organization to use the 
  Configuration Designer
  .
  cost-estimation
   — Allows an organization to access 
  cost estimation
  .
  global-run-tasks
   — Allows an organization to apply 
  run tasks
   to every workspace. Affects the 
  run 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.
  module-deprecations
   - Allows an organization to mark a module version from the Private Registry as deprecated.
  module-revocations
   - Allows an organization to mark a deprecated module version from the Private Registry as revoked.
  operations
   — Allows an organization to perform runs within HCP Terraform. Affects the 
  runs
  , 
  plans
  , and 
  applies
   endpoints.
  policy-enforcement
   — Allows an organization to use 
  Sentinel
  . Affects the 
  policies
  , 
  policy sets
  , and 
  policy checks
   endpoints.
  private-module-registry
   — Allows an organization to publish and use modules with the 
  private module registry
  . Affects the 
  registry modules
   endpoints.
  private-policy-agents
   - Allows an organization to ensure that HTTP enabled 
  Sentinel
   and OPA 
  policies
   can communicate with isolated, private, or on-premises infrastructure.
  private-run-tasks
   - Allows an organization to ensure that 
  run tasks
   can communicate with isolated, private, or on-premises infrastructure.
  private-vcs
   - Allows a self-hosted HCP Terraform agent to 
  connect to a private VCS provider
   without having to expose that provider to the public internet.
  run-tasks
   — Allows an organization to use 
  run tasks
  . Affects the 
  run tasks
   endpoints.
  self-serve-billing
   — Allows an organization to pay via credit card using the in-app billing UI.
  sentinel
   -  
  DEPRECATED
   Use 
  policy-enforcement
   instead.
  state-storage
   — Allows an organization to store state versions in its workspaces, which enables local Terraform runs with HCP Terraform. Affects the 
  state 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 with 
  teams
  . Without this entitlement, an organization only has an owners team. Affects the 
  teams
  , 
  team members
  , 
  team access
  , and 
  team 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 to 
  connect with a VCS provider
   and link VCS repositories to workspaces. Affects the 
  OAuth Clients
  , and 
  OAuth Tokens
   endpoints, and determines whether the 
  data.attributes.vcs-repo
   property can be set for 
  workspaces
  .
  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 the 
  JSON 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 return 
  JSON 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-level 
  data
   property, which:
  Must have a 
  type
   property to indicate what type of API object you're interacting with.
  Often has an 
  attributes
   property to specify attributes of the object you're creating or modifying.
  Sometimes has a 
  relationships
   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:
  Key path
  Type
  Default
  Description
  data.type
  string
  Must be 
  "vars"
  .
  data.attributes.key
  string
  The name of the variable.
  data.attributes.value
  string
  The value of the variable.
  data.attributes.category
  string
  Whether this is a Terraform or environment variable. Valid values are 
  "terraform"
   or 
  "env"
  .
  data.attributes.hcl
  bool
  false
  Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
  data.attributes.sensitive
  bool
  false
  Whether the value is sensitive. If true then the variable is written once and not visible thereafter.
  data.relationships.workspace.data.type
  string
  Must be 
  "workspaces"
  .
  data.relationships.workspace.data.id
  string
  The ID of the workspace that owns the variable.
  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 be 
  percent-encoded
   in a query parameter. For example, 
  [
   becomes 
  %5B
   and 
  ]
   becomes 
  %5D
  .
  For more about URI structure and query strings, see 
  the specification (RFC 3986)
   or 
  the 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:
  Parameter
  Description
  page[number]
  Optional.
   If omitted, the endpoint will return the first page.
  page[size]
  Optional.
   If omitted, the endpoint will return 20 items per page. The maximum page size is 100.
  Additional data is returned in the 
  links
   and 
  meta
   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 an 
  include
   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 an 
  included
   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 limits
  You can make up to 30 requests per second to most API endpoints 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.
  Requests are per user, not per token. As a result, you cannot use multiple tokens to make more than 30 requests per second.
  Unauthenticated requests are associated with the requesting IP address.
  Status
  Response
  Reason
  429
  JSON API error object
  Rate limit has been reached.
  {
  
    "errors"
  :
   [
  
      {
  
        "detail"
  :
   "You have exceeded the API's rate limit."
  ,
  
        "status"
  :
   429
  ,
  
        "title"
  :
   "Too many requests"
  
      }
  
    ]
  
  }
  
  Lower rate limits for some endpoints
  To prevent abuse, some endpoints have lower rate limits. The lower limits are unnoticeable under normal use. If you trigger a rate-limited response, you can see that limit in the 
  x-ratelimit-limit
   header.
  The following endpoints have lower rate limits:
  Method and endpoint
  Purpose
  Limit
  POST /session/two-factor-send-sms
  POST /api/v2/account/actions/two-factor-enable
  POST /api/v2/account/actions/two-factor-resend-verification-code
  Send SMS message
  5 requests per minute per user
  POST /api/v2/account/actions/two-factor-enable
  POST /api/v2/account/actions/two-factor-resend-verification-code
  Send SMS message
  10 requests per hour per user
  POST /api/v2/account/actions/two-factor-enable
  POST /api/v2/account/actions/two-factor-resend-verification-code
  Send SMS message
  100 requests per day per IP address
  POST /session/two-factor
  POST /session/two-factor-recovery
  Submit 2FA code
  5 requests per minute per user
  POST
   and 
  PATCH /api/v2/account/create
  POST
   and 
  PATCH /api/v2/account/update
  POST
   and 
  PATCH /api/v2/account/password
  POST
   and 
  PATCH /api/v2/account/reconfirm
  POST /session
  Send emails
  100 per minute
  POST
   and 
  GET /sso/link-new-account
  POST
   and 
  GET /sso/link-account
  POST
   and 
  GET /sso/link-existing-account
  POST /sso/saml/{SAML_CONFIGURATION_EXTERNAL_ID}/acs
  Send emails
  20 per minute
  POST /api/v2/notification-configurations/{EXTERNAL_ID}/actions/verify
  DELETE /api/v2/oauth-tokens
  Send emails
  10 per minute
  POST /account/reconfirm
  Send emails
  40 per hour
  POST /auth
  Send emails
  40 per hour per email address
  Client libraries and tools
  HashiCorp maintains 
  go-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, please 
  contribute
   to 
  this 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
  Edit this page on GitHub
  
  ## Code Examples
  
  ```text
  https://archivist.terraform.io/v1/object/<secret value>
  ```
  
  ```json
  {
    "data": {
      "type":"vars",
      "attributes": {
        "key":"some_key",
        "value":"some_value",
        "category":"terraform",
        "hcl":false,
        "sensitive":false
      },
      "relationships": {
        "workspace": {
          "data": {
            "id":"ws-4j8p6jX1w33MiDC7",
            "type":"workspaces"
          }
        }
      }
    }
  }
  ```
  
  ```json
  {
    "data": {
      "type":"vars",
      "attributes": {
        "key":"some_key",
        "value":"some_value",
        "category":"terraform",
        "hcl":false,
        "sensitive":false
      },
      "relationships": {
        "workspace": {
          "data": {
            "id":"ws-4j8p6jX1w33MiDC7",
            "type":"workspaces"
          }
        }
      }
    }
  }
  ```
  
  ```json
  {
    "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
      }
    }
  }
  ```
  
  ```json
  {
    "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
      }
    }
  }
  ```
  
  ```text
  $ 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
  ```
  
  ```text
  $ 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
  ```
  
  ```json
  {
    "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"
          ...
        } ...
      }
    ]
  }
  ```
  
  ```json
  {
    "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"
          ...
        } ...
      }
    ]
  }
  ```
  
  ```json
  {
    "errors": [
      {
        "detail": "You have exceeded the API's rate limit.",
        "status": 429,
        "title": "Too many requests"
      }
    ]
  }
  ```
  
  ```json
  {
    "errors": [
      {
        "detail": "You have exceeded the API's rate limit.",
        "status": 429,
        "title": "Too many requests"
      }
    ]
  }
  ```
  
  ```text
  POST /api/v2/account/actions/two-factor-resend-verification-code
  ```
  
  ```text
  POST /api/v2/account/actions/two-factor-resend-verification-code
  ```
  
  ```text
  POST /api/v2/account/actions/two-factor-resend-verification-code
  ```
  
  ```text
  POST /sso/saml/{SAML_CONFIGURATION_EXTERNAL_ID}/acs
  ```
  
  ```text
  POST /api/v2/notification-configurations/{EXTERNAL_ID}/actions/verify
  ```