RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://developer.hashicorp.com/terraform/enterprise/api-docs below:

API documentation for Terraform Enterprise | Terraform

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

The API includes endpoints for system-level operations, such as health checks and usage reporting. System endpoints have different authentication and rate limiting requirements than application endpoints. Refer to the following documentation for details about system endpoints:

/api/v1/ping. Call this endpoint to verify system operation.
/api/v1/usage/bundle. Call this endpoint to retrieve a usage data bundle.

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.

System endpoints

Requests to the /api/v1/ping and /api/v1/usage/bundle endpoints must be authenticated with a bearer token generated specifically for them using the tfectl admin api-token generate command. For more information on the token creation, and management, refer to the tfectl documentation.

Use the HTTP Header Authorization with the value Bearer <token>.

Blob storage authentication

Terraform Enterprise relies on a HashiCorp-developed blob storage service for storing state files and other pieces of customer data.

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.

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

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.

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.

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.

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

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"
        ...
      } ...
    }
  ]
}

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.

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

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

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4