Merge branch 'main' into RK/tfe-may-release-to-tfc

rkoron007 · web-flow · commit eb9d3b8951bb · 2025-06-06T09:20:36.000-07:00
diff --git a/content/terraform-docs-common/docs/cloud-docs/integrations/service-now/service-catalog-terraform/index.mdx b/content/terraform-docs-common/docs/cloud-docs/integrations/service-now/service-catalog-terraform/index.mdx
@@ -110,17 +110,12 @@ Terraform.
    **Save the organization name for later.**
 2. [Create a team](/terraform/cloud-docs/users-teams-organizations/teams) for that
    organization called "ServiceNow", and ensure that it has [permission to
-   manage
-   workspaces](/terraform/cloud-docs/users-teams-organizations/permissions#manage-all-workspaces).
+   manage workspaces](/terraform/cloud-docs/users-teams-organizations/permissions#manage-all-workspaces).
    You do not need to add any users to this team.
    [permissions-citation]: #intentionally-unused---keep-for-maintainers
 3. On the "ServiceNow" team's settings page, generate a [team API
-   token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens).
+   token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens). HCP Terraform now supports fine-grained permissions for team tokens at the project level. You can assign teams and their associated tokens permission levels on specific projects. To learn more about the different permissions necessary to provision resources, refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions). 
    **Save the team API token for later.**
-4. After [generating a team token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens) in HCP Terraform, you can add that token to your ServiceNow context by doing the following:
-    1. Navigate to **Terraform Configs** in ServiceNow
-    2. Select **New** and add your token.
-    3. Use your HCP Terraform team name as your **Org name**.   
 5. If you are using the [VCS flow](/terraform/cloud-docs/integrations/service-now/service-catalog-terraform/service-catalog-config#vcs-configuration): 
     1. Ensure your Terraform organization is [connected to a VCS provider](/terraform/cloud-docs/vcs). Repositories that are connectable to HCP Terraform workspaces can also be used as workspace templates in the ServiceNow integration.
     2. On your organization's VCS provider settings page (**Settings** > **VCS Providers**), find the OAuth Token ID for the VCS provider(s) that you intend to use with the ServiceNow integration. HCP Terraform uses the OAuth token ID to identify and authorize the VCS provider. **Save the OAuth token ID for later.**
@@ -224,8 +219,7 @@ update request items.
 ### Team Tokens
 
 Team-scoped tokens can help you manage a team's access to things in HCP Terraform, but team tokens are limited within the ServiceNow context. We recommend only using one API team token, regardless of the number of teams accessing ServiceNow. 
-
-You can assign teams and their associated tokens permission levels on specific projects. To learn more about the different permissions necessary to provision resources, refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions). To learn more about API tokens, refer to [Team tokens](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens).
+To learn more about API tokens, refer to [Team tokens](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens).
 
 ### ServiceNow Developer Reference
 
diff --git a/content/terraform-enterprise/v202505-1/data/enterprise-nav-data.json b/content/terraform-enterprise/v202505-1/data/enterprise-nav-data.json
@@ -52,6 +52,8 @@
           }
         ]
       },
+      { "title": "Ping", "path": "api-docs/ping" },
+      { "title": "Usage Bundle", "path": "api-docs/usage-bundle" },
       {
         "title": "Agent Pools",
         "path": "api-docs/agents"
diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/index.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/index.mdx
@@ -38,27 +38,52 @@ source: terraform-docs-common
 
 [JSON API error object]: https://jsonapi.org/format/#error-objects
 
-# HCP Terraform API documentation
+# API Documentation
+
+## HCP Terraform API
 
 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](https://support.hashicorp.com/hc/en-us) and open a ticket.
 
 -> **Note:** Before planning an API integration, consider whether [the `tfe` Terraform provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) 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.
 
 HashiCorp provides a [stability policy](/terraform/enterprise/api-docs/stability-policy) for the HCP Terraform API, ensuring backwards compatibility for stable endpoints. The [changelog](/terraform/enterprise/api-docs/changelog) tracks changes to the API for HCP Terraform and Terraform Enterprise.
 
+## API Types
+
+HCP Terraform provides two types of API endpoints:
+
+- **Application Endpoints** - These are the primary endpoints used for interacting with HCP Terraform resources such as workspaces, runs, and variables. Unless otherwise specified, all documentation on this site refers to application endpoints.
+- **System Endpoints** - These endpoints are used for system-level operations, such as health checks and usage reporting. System endpoints have different authentication and rate limiting requirements than application endpoints.
+
+### System Endpoints Overview
+
+The following table lists the available system API endpoints in Terraform Enterprise:
+
+| Endpoint | Description | Path | Documentation |
+|---------|-------------|------|---------------|
+| Ping | Health check endpoint to verify system operation | `/api/v1/ping` | [System Ping API](/terraform/enterprise/api-docs/ping) |
+| Usage/Bundle | Retrieves usage data bundle | `/api/v1/usage/bundle` | [System Usage/Bundle API](/terraform/enterprise/api-docs/usage-bundle) |
+
+-> **Terraform Enterprise Only:** The System API is exclusive to Terraform Enterprise. It enables access to deployment configuration and data.
+
 ## 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][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.
+### Application Endpoints
+
+For application endpoints, 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][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](/terraform/enterprise/users-teams-organizations/users#api-tokens) — each HCP Terraform user can have any number of API tokens, which can make requests on their behalf.
--   [Team tokens](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-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](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-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.
+-   [User tokens](/terraform/enterprise/users-teams-organizations/users#api-tokens) — each HCP Terraform user can have any number of API tokens, which can make requests on their behalf.
+-   [Team tokens](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-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](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-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.
     <!-- BEGIN: TFC:only -->
--   [Audit trails token](/terraform/enterprise/users-teams-organizations/api-tokens#audit-trails-tokens) - 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](/terraform/enterprise/integrations/splunk) app.
+-   [Audit trails token](/terraform/enterprise/users-teams-organizations/api-tokens#audit-trail-tokens) - 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](/terraform/enterprise/integrations/splunk) app.
     <!-- END: TFC:only -->
 
+### System Endpoints
+@include "api-code-blocks/authentication.mdx"
+
 ### 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](/terraform/enterprise/architectural-details/data-security).
@@ -175,16 +200,20 @@ We return 404 Not Found codes for resources that a user doesn't have access to,
 
 ## Versioning
 
-The API documented in these pages is the second version of HCP Terraform's API, and resides under the `/v2` prefix.
+The API documented in these pages is the second version of HCP Terraform's application 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.
 
+System endpoints may follow different versioning patterns, which are documented in their respective sections.
+
 ## Paths
 
-All V2 API endpoints use `/api/v2` as a prefix unless otherwise specified.
+All V2 application 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`.
 
+System endpoints follow their own path structure, which is documented in their respective pages.
+
 ## JSON API Formatting
 
 The HCP Terraform endpoints use the [JSON API specification](https://jsonapi.org/), which specifies key aspects of the API. Most notably:
@@ -342,7 +371,9 @@ $ curl \
 
 ## Rate Limiting
 
-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.
+### Application Endpoints
+
+You can make up to 30 requests per second to the application 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. 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 the `x-ratelimit-limit` header once triggered.
 
 Requests are per user, not per token. As a result, you cannot use multiple tokens to make more than 30 requests per second.
 
@@ -364,7 +395,7 @@ Unauthenticated requests are associated with the requesting IP address.
 }
 ```
 
-### Lower rate limits for some endoints
+#### 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.
 
@@ -382,6 +413,9 @@ The following endpoints have lower rate limits:
 | <p>`POST /account/reconfirm`</p>                                                                                                                                                                                            | Send emails      | 40 per hour                         |
 | <p>`POST /auth`</p>                                                                                                                                                                                                         | Send emails      | 40 per hour per email address       |
 
+### System Endpoints
+@include "api-code-blocks/rate-limit.mdx"
+
 ## Client libraries and tools
 
 HashiCorp maintains [go-tfe](https://github.com/hashicorp/go-tfe), a Go client for HCP Terraform's API.
diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/ping.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/ping.mdx
@@ -0,0 +1,31 @@
+---
+page_title: System Ping API reference for Terraform Enterprise
+description: >-
+  Use the Ping endpoint to check the health of the System API of your Terraform Enterprise system.
+---
+
+# `/ping` endpoint reference
+
+This endpoint provides a simple health check to verify that the Terraform Enterprise system is operational. Authentication is required to use this endpoint.
+
+`GET /api/v1/ping`
+
+## Sample request
+
+```shell
+curl \
+  --header "Authorization: Bearer $TOKEN" \
+  --request GET \
+  https://tfe.example.com:8443/api/v1/ping
+```
+
+## Response codes
+
+| Status  | Response | Reason                             |
+| ------- | -------- | ---------------------------------- |
+| [200][] | `pong`   | The system is operational          |
+| [403][] | [JSON API error object][] | Not authorized to access this endpoint     |
+| [429][] | [JSON API error object][] | Too many requests                          |
+| [500][] | [JSON API error object][] | Internal server error                      |
+
+@include "api-code-blocks/system-api.mdx"
diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/usage-bundle.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/api-docs/usage-bundle.mdx
@@ -0,0 +1,36 @@
+---
+page_title: System Usage/Bundle API reference for Terraform Enterprise
+description: >-
+  Use the Usage/Bundle endpoint to download a usage bundle.
+---
+
+# `/usage/bundle` endpoint reference
+
+This endpoint provides a usage bundle. For more information about the product usage data structure and the specific metrics that Terraform Enterprise collects, refer to the [Terraform Enterprise usage data reference](/terraform/enterprise/deploy/reference/product-data).
+
+`GET /api/v1/usage/bundle`
+
+## Sample request
+
+```shell
+curl \
+  --header "Authorization: Bearer $TOKEN" \
+  --request GET \
+  https://tfe.example.com:8443/api/v1/usage/bundle
+```
+
+### Response Codes
+
+| Status  | Response                  | Reason                                     |
+| ------- | ------------------------- | ------------------------------------------ |
+| [200][] | JSON usage bundle         | Successfully retrieved usage data          |
+| [403][] | [JSON API error object][] | Not authorized to access this endpoint     |
+| [429][] | [JSON API error object][] | Too many requests                          |
+| [500][] | [JSON API error object][] | Internal server error                      |
+
+@include "api-code-blocks/system-api.mdx"
+
+## Related Resources
+
+* [Enable automated product usage reports](/terraform/enterprise/deploy/manage/product-report) - Instructions for configuring Terraform Enterprise to automatically send product usage data to HashiCorp
+* [Generate product usage report using the CLI](/terraform/enterprise/deploy/reference/cli#generate-product-usage-report) - Instructions for generating product usage reports manually
diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/deploy/reference/cli.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/deploy/reference/cli.mdx
@@ -164,6 +164,42 @@ Each specific run of the admin `usage-report` command generates the product usag
 
 To send product usage reports to HashiCorp, visit the [**Licensing utilization reporting** page](https://portal.cloud.hashicorp.com/license-utilization/reports/create) and use the upload form.
 
+## Manage admin API tokens
+
+Terraform Enterprise provides commands to manage authentication tokens for the Admin API, which allows programmatic access to administrative functions.
+
+### Generate an admin API token
+
+To create a new admin API token, use the `admin api-token generate` command with a required description that helps identify the token's purpose or owner:
+
+```shell-session
+$ tfectl admin api-token generate --description "Token description"
+```
+
+By default, tokens expire after 720 hours (30 days). You can specify a custom time-to-live (TTL) in hours using the `--ttl` flag:
+
+```shell-session
+$ tfectl admin api-token generate --description "Token description" --ttl 2000
+```
+
+### List admin API tokens
+
+To list all existing admin API tokens along with their metadata (excluding the actual token value), use:
+
+```shell-session
+$ tfectl admin api-token list
+```
+
+This command displays the token ID, creation date, expiration date, last used date, and description for each token. The output is ordered by creation date.
+
+### Revoke an admin API token
+
+To revoke an admin API token, use the `admin api-token revoke` command with the token ID (obtained from the `list` command):
+
+```shell-session
+$ tfectl admin api-token revoke --id "1"
+```
+
 ## List all Terraform Enterprise installation nodes
 
 To get a list of valid node values, use the following command:
diff --git a/content/terraform-enterprise/v202505-1/docs/enterprise/deploy/reference/configuration.mdx b/content/terraform-enterprise/v202505-1/docs/enterprise/deploy/reference/configuration.mdx
@@ -371,6 +371,11 @@ Specifies which hostname Terraform Enterprise should use to federate run task wo
 
 Default is `primary`.
 
+### `TFE_ADMIN_HTTPS_PORT`
+
+Specifies the port that the [system API endpoints](/terraform/enterprise/api-docs/index#system-endpoints-overview) listen on for HTTPS requests.
+Defaults to `8443`.
+
 ## Observability settings
 
 ### `TFE_LOG_FORWARDING_CONFIG_PATH`
diff --git a/content/terraform-enterprise/v202505-1/docs/partials/api-code-blocks/authentication.mdx b/content/terraform-enterprise/v202505-1/docs/partials/api-code-blocks/authentication.mdx
@@ -0,0 +1,2 @@
+System API requests must be authenticated with a bearer token generated specifically for this API using the `tfectl admin api-token generate` command. For more information on the token creation, and management, refer to the [tfectl documentation](/terraform/enterprise/deploy/reference/cli).
+Use the HTTP Header `Authorization` with the value `Bearer <token>`.
diff --git a/content/terraform-enterprise/v202505-1/docs/partials/api-code-blocks/rate-limit.mdx b/content/terraform-enterprise/v202505-1/docs/partials/api-code-blocks/rate-limit.mdx
@@ -0,0 +1 @@
+All System API endpoints are rate limited to 1 request per second per authentication token.
diff --git a/content/terraform-enterprise/v202505-1/docs/partials/api-code-blocks/system-api.mdx b/content/terraform-enterprise/v202505-1/docs/partials/api-code-blocks/system-api.mdx
@@ -0,0 +1,32 @@
+[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200
+[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
+[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
+[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
+[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
+[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429
+[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
+[JSON API error object]: https://jsonapi.org/format/#error-objects
+
+## System API Overview
+
+-> **Terraform Enterprise Only:** The System API is exclusive to Terraform Enterprise. It enables access to deployment configuration and data. 
+
+This API is distinct from the regular Admin API and the Backup and Restore API, with its own authentication mechanism.
+
+## Authentication
+@include "api-code-blocks/authentication.mdx"
+
+## Rate Limiting
+@include "api-code-blocks/rate-limit.mdx"
+
+## Port Configuration
+
+By default, the System API is accessible on HTTPS port `8443`. This port can be configured through the `TFE_ADMIN_HTTPS_PORT` environment variable in your deployment configuration.
+
+Refer to [Network settings](/terraform/enterprise/deploy/reference/configuration#network-settings) in the configuration reference for more information about network configuration.
+
+## Versioning
+
+The System API is versioned under the `/api/v1` prefix and is separate from the main Terraform Enterprise API.
+
+For example, if the API endpoint documentation defines the path `/ping` then the full path is `/api/v1/ping`.

Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,8 @@`
`52`	`52`	`}`
`53`	`53`	`]`
`54`	`54`	`},`
	`55`	`+ { "title": "Ping", "path": "api-docs/ping" },`
	`56`	`+ { "title": "Usage Bundle", "path": "api-docs/usage-bundle" },`
`55`	`57`	`{`
`56`	`58`	`"title": "Agent Pools",`
`57`	`59`	`"path": "api-docs/agents"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+System API requests must be authenticated with a bearer token generated specifically for this API using the `tfectl admin api-token generate` command. For more information on the token creation, and management, refer to the [tfectl documentation](/terraform/enterprise/deploy/reference/cli).
	`2`	+Use the HTTP Header `Authorization` with the value `Bearer <token>`.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+All System API endpoints are rate limited to 1 request per second per authentication token.`