Terraform package v1.0.0

An HCP Terraform API token for the customer's own organization, held in the client's own secret manager. The stored material must be the complete Authorization header value: the scheme 'Bearer', one separating space, then the token — 'Bearer <token>'.

Issuance is external and three token types exist according to the reviewed API overview: user tokens (each user can have any number, created on the user's account settings page), team tokens (created in the team's settings and intended for plans and applies via CI/CD; according to the reviewed token-management documentation the CURRENT team token API allows multiple valid tokens per team when their descriptions are unique — only legacy tokens are one-at-a-time) and organization tokens (one per organization, intended for automating team and workspace management — and per the same reference, organization tokens CANNOT perform plans and applies).

This pack's run capabilities require a user or team token; prefer a team token on a dedicated least-privilege team so the credential is not a person's identity.

Least privilege: place that team on only the workspaces the deployment binds, with Read permission for the collection reads, and Apply runs / Admin permissions only where the run and workspace-write capabilities are enabled.

Expiry and revocation: per HashiCorp's token-management documentation (retrieved during the documented review and appended to the review sources), each user, team and organization token HAS an expiration date and time chosen at creation — it cannot be modified afterward, any API request made with an expired token fails, HCP Terraform sends notification emails 30 days and 7 days before expiry, and organization owners can set a maximum token time-to-live in the organization's settings; the custody job must therefore record the expiry stamped at issuance and rotate before it rather than treating the token as valid until revoked.

Revocation is explicit: delete the individual user, team or organization token in settings (team tokens can be deleted individually or in bulk, and only organization owners can generate or revoke the organization token); a deleted value fails closed with a 401. Token multiplicity differs by type and matters for rotation: an organization can have only ONE valid organization token at a time, but the CURRENT team token API supports MULTIPLE valid team tokens at a time (descriptions unique within the team) and adding a new team token does NOT invalidate older ones — only the legacy team-token API is one-at-a-time, where generating a new legacy token invalidates the previous one; so minting a successor does not retire the old team token, and every issued token must be deleted individually at end of life. HCP Terraform displays an API token only once at creation and obfuscates it thereafter, so a lost value must be regenerated, not retrieved.

Rotation therefore sits with an external deployment process: the executor injects the stored value verbatim and performs no token lifecycle of its own. A fourth token type, the audit trails token, reads only the organization's audit trails and cannot serve any capability in this pack.

Executor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack.

The endpoint host 'terraform-cloud.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the customer's HCP Terraform host (app.terraform.io) or Terraform Enterprise hostname before enabling, in every endpoint, in the resource locator and in every egress allowlist entry. The allowlist matches exactly, so endpoints and allowlist must be substituted together, and substitution is a required deployment step. ORG, WORKSPACE_ID and RUN_ID in the endpoint paths are placeholders the deployment binds before enabling.

Per the retrieved API overview the API is version 2 under the /api/v2 prefix and speaks JSON:API (Content-Type application/vnd.api+json), POST and PATCH endpoints take a JSON:API document as the request payload, and list endpoints paginate with page[number]/page[size] query parameters. Token types: according to the reviewed overview, ORGANIZATION tokens cannot perform plans and applies, so the run create/apply/discard capabilities require a user or team token, and forbidden requests with a valid token return 404 rather than 403 — a capability that inexplicably 404s is a permissions finding, not an absence of the resource.

Approval classification: run creation registers as create, deploy AND delete at the minimum R3 tier, judged by effect — according to the reviewed Runs reference a run performs a plan and apply, and the caller-controlled body can set auto-apply (apply without a further confirmation step), is-destroy=true (the plan destroys ALL provisioned resources in the workspace) and target/replace addresses — so an unrestricted body can both deploy infrastructure change and destroy the whole estate a workspace manages; deploy and delete are designated actions requiring human approval and an installer's intention to queue only plan-only runs is not a restriction.

Applying a run registers as approve, deploy AND delete at the minimum R3 tier: the apply action confirms a run paused for confirmation and queues the apply of the reviewed plan — it is precisely the approval moment — and the plan being applied may itself destroy managed resources, so delete is declared as well. Discarding a run registers as delete at the minimum R3 tier: discard is terminal (the run reaches its discarded final state and later runs can proceed), and queuing a fresh run afterward is a new run, not a reversal of the discard.

Workspace creation registers as create AND deploy at the minimum R3 tier: according to the reviewed Workspaces reference the unrestricted body can link a VCS repository with automatic run triggering, speculative plans and auto-apply, and those VCS-triggered executions run provider-side — they need not traverse terraform.run.create or terraform.run.apply or any other AAES capability. Workspace deletion registers as delete at the minimum R3 tier: according to the reviewed Workspaces reference, DELETE /workspaces/{id} FORCE-deletes the workspace WITHOUT first checking for managed resources — destroying nothing itself but orphaning real infrastructure whose management record is gone; the checking form (POST .../actions/safe-delete, which refuses while resources are managed) is deliberately not registered, so this pack's only workspace deletion is the force form and the description says so.

Documented exclusions — this pack does not register: state versions and state version outputs (state routinely contains cleartext secrets, and hosted-state download URLs are themselves bearer-secret URLs according to the reviewed overview), variable creation/update (writing variables injects configuration, including sensitive values, into future runs), configuration-version upload, run force-execute and force-cancel (according to the reviewed Runs reference, force-cancel warns of potentially dangerous side effects including loss of in-flight state), policy check overrides, workspace lock/unlock/force-unlock, team and organization membership management, agent pools and agent tokens, SSH keys, organization tokens and audit-trails tokens, and every other HCP Terraform API.