> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Manage Forge policy resources with exclusive Terraform authority.

The Forge provider intentionally manages policies and policy-adjacent routing
only. Identities, integrations, products, models, MCP servers, and skills stay
server-owned and are referenced by readable names.

The public provider is published in the Terraform Registry as
[`a37ai/forge`](https://registry.terraform.io/providers/a37ai/forge/latest).
The v0.3 release line includes signed checksums and provider packages for
Darwin, Linux, and Windows on amd64 and arm64.

## Configure the provider

```hcl theme={"system"}
terraform {
  required_version = ">= 1.8.0"

  required_providers {
    forge = {
      source  = "a37ai/forge"
      version = "~> 0.3.0"
    }
  }
}

provider "forge" {
  organization_id  = "org.example"
  manager_id       = "policy-repository"
  manager_instance = "production"
}
```

Set `FORGE_API_TOKEN` to a Forge service-account token with `policies:read` and
`policies:write`. `endpoint` defaults to
`https://api.forge.ai` and can be supplied with `FORGE_ENDPOINT`.
Plain HTTP is accepted only for localhost development.

`manager_id` identifies the durable policy manager, such as a repository.
`manager_instance` distinguishes independent deployments, such as production
and staging. Keep both stable; changing them makes existing authority checks
fail.

The server binds `manager_id` and `manager_instance` to the authenticated
service-account principal that first claims or creates the policy. Matching
headers from another credential cannot read, update, release, or delete that
Terraform-owned policy. The values identify state ownership; they are not
secrets and do not replace token authorization.

The provider checks compatibility with Forge before planning a mutation. A
connected plan validates readable references, policy structure, Rego, the
current revision, and policy ownership. Apply rechecks the reviewed plan and
fails before changing the policy if a relevant remote value changed. The
provider refreshes short-lived validation automatically at apply while keeping
the exact definition, references, revision, and manager binding unchanged.

## Resources

| Resource                           | Purpose                                                                                                                                            |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `forge_content_policy`             | Content policy with either native conditions or `forge.rego.v1` match logic, typed scope, stages, action, approval, redaction, and filtering       |
| `forge_access_policy`              | Access policy with either native conditions or `forge.rego.v1` match logic, typed scope, action, approval, and remediation                         |
| `forge_llm_gateway_access_profile` | Native gateway access profile, model selectors, and atomic provider route plan used by the production gateway runtime; gateway keys assign callers |
| `forge_mcp_acl`                    | Readable MCP server/tool ACL compiled to a Content policy                                                                                          |
| `forge_skill_acl`                  | Readable skill grant or block                                                                                                                      |
| `forge_policy_authority`           | Explicitly claim/release an existing Forge-managed policy at an expected revision                                                                  |

Typed data sources resolve one exact customer-visible selector through the same
organization-scoped resolver used by connected plans:

| Data source                                         | Resolves                                                                                                        |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `forge_user`, `forge_group`                         | Active directory subjects; optional qualifier disambiguates duplicate labels                                    |
| `forge_agent`, `forge_ai_product`                   | Inventory targets with actual Content-policy applicability                                                      |
| `forge_integration`                                 | Connected integration or supported enforcement connection                                                       |
| `forge_mcp_server`, `forge_mcp_tool`, `forge_skill` | Approved registry objects; MCP tools require a resolved parent server                                           |
| `forge_gateway_provider`                            | Configured LLM Gateway provider                                                                                 |
| `forge_rego_test`                                   | Compiles and evaluates a module against native HCL input and asserts the expected match during `terraform test` |

Missing and ambiguous references fail rather than selecting the first result.

### Production validation

Qualify each resource against your target Forge environment before production
rollout. Use the same provider version, service-account scopes, organization,
manager identity, and remote state backend that you will use in production.

| Resource                           | Required pre-production lifecycle checks                                                                                                        |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `forge_content_policy`             | Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy.                                              |
| `forge_access_policy`              | Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy.                                              |
| `forge_llm_gateway_access_profile` | Create, refresh/no-op, route-plan update, import, exclusive-ownership rejection, and destroy; verify the resulting live gateway route.          |
| `forge_mcp_acl`                    | Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy; verify the resulting live MCP decision.      |
| `forge_skill_acl`                  | Create, refresh/no-op, update, import, drift recovery, exclusive-ownership rejection, and destroy; verify the resulting live skill decision.    |
| `forge_policy_authority`           | Claim at the reviewed revision, reject stale revisions and other managers, import the matching policy, release, and confirm the policy remains. |

For every row, confirm that failed validation or ownership checks leave the
remote resource unchanged, the final no-op plan is empty, and the Forge audit
trail identifies the expected service account and manager.

### Import IDs

Every resource imports by its stable Forge identifier:

| Resource                           | Import value                                  |
| ---------------------------------- | --------------------------------------------- |
| `forge_content_policy`             | Policy `id`                                   |
| `forge_access_policy`              | Policy `id`                                   |
| `forge_llm_gateway_access_profile` | Profile `id`                                  |
| `forge_mcp_acl`                    | ACL `id`                                      |
| `forge_skill_acl`                  | ACL `id`                                      |
| `forge_policy_authority`           | Existing policy `id`, loaded into `policy_id` |

Import reads state; it never bypasses or implicitly claims policy authority.

### Provider arguments

| Argument           | Required | Description                                                         |
| ------------------ | -------- | ------------------------------------------------------------------- |
| `organization_id`  | Yes      | Forge organization to manage                                        |
| `manager_id`       | Yes      | Stable durable manager/repository identity                          |
| `manager_instance` | Yes      | Stable deployment/state identity                                    |
| `api_token`        | No       | Sensitive token; prefer `FORGE_API_TOKEN`                           |
| `endpoint`         | No       | Control-plane URL; defaults to `FORGE_ENDPOINT` then the hosted API |

## Reference

<CardGroup cols={2}>
  <Card title="Policy Resources" icon="shield-check" href="/developer/policy-resources">
    Content and Access schemas, native conditions, actions, examples, and
    readable references.
  </Card>

  <Card title="Gateway Profile" icon="route" href="/developer/gateway-profile">
    LLM gateway access-profile and route-plan attributes with a complete
    example.
  </Card>

  <Card title="Registry ACLs" icon="list-checks" href="/developer/registry-acls">
    MCP and skill ACL resources, parameter descriptions, and examples.
  </Card>

  <Card title="Conditions" icon="git-branch" href="/secure/conditions">
    Canonical field types, exact meanings, operators, and history-aware
    matching.
  </Card>
</CardGroup>

## Authority

| Attribute                         | Requirement and type                 | Exact meaning                                                                                 |
| --------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `policy_id`                       | Required string; forces replacement  | Existing Forge-managed durable policy ID to claim.                                            |
| `expected_revision`               | Required integer; forces replacement | Revision reviewed by the operator. The claim fails atomically if the remote revision differs. |
| `id`                              | Computed string                      | Provider state identity for the authority binding.                                            |
| `current_revision`                | Computed integer                     | Revision present when the binding is read.                                                    |
| `management_mode`                 | Computed string                      | Must be `terraform` after a successful claim.                                                 |
| `manager_id` / `manager_instance` | Computed strings                     | Server-confirmed exclusive manager binding; must equal provider configuration.                |

Replacement or destroy releases the claim; it does not disable, delete, or
tombstone the underlying policy.

## Ownership, adoption, and import

New resources are atomically created as Terraform-managed. To adopt an existing
Forge-managed policy:

```hcl theme={"system"}
resource "forge_policy_authority" "customer_export" {
  policy_id         = "customer-export"
  expected_revision = 7
}
```

1. Read the policy's current revision and review its definition.
2. Apply `forge_policy_authority`; the claim fails if the revision changed.
3. Keep the authority resource in state.
4. Add the corresponding policy resource with the exact remote definition.
5. Import it, for example:

```bash theme={"system"}
terraform import forge_content_policy.customer_export customer-export
```

Import never claims authority implicitly. Importing before a claim, using a
different manager binding, or removing the authority resource while the policy
remains in state produces an authority error. Destroying the authority resource
releases ownership back to Forge; destroying a policy resource disables and
tombstones the policy.

An organization owner can use **Break glass** on the console's read-only policy
view during an active incident. Forge requires a 10–1,024 character reason,
creates a new immutable revision, records the owner and reason in the audit
trail, atomically changes authority to `forge`, and clears the Terraform
binding. The old state cannot revert the emergency revision: refresh reports
lost authority and recovery requires an explicit reviewed claim or transfer.

## Drift, retries, and state

* Updates use the last observed immutable revision for optimistic concurrency.
* Refresh verifies the exact Terraform manager and restores readable selectors.
* Remote `404` removes the resource from Terraform state.
* Destroy records a forward-only tombstone. The same authenticated
  `manager_id` + `manager_instance` can recreate that resource from the same
  state after destroy; the server assigns the next revision and preserves the
  complete history. A different manager cannot reuse the tombstoned ID.
* Reads, updates, and deletes have bounded retries for `429` and `5xx` errors.

Use `lifecycle { prevent_destroy = true }` for policies that need a separate
retirement review. Terraform state contains policy configuration, sensitive
match values, and an expiring signed plan-binding token; store it in an
encrypted backend with narrow access.
Never put API tokens or secret material in Rego source, selector names,
descriptions, or filter values.

Terraform applies resources independently. A multi-resource plan is not an
atomic policy bundle: earlier resources can commit while a later reference,
validation, authority, or network error fails the apply. Use one remote state
writer, preserve the saved plan, and run a refresh plus policy-impact review
after any partial failure.

This guide assumes state created with a v0.3.x provider. Review the release
notes and a saved plan before upgrading earlier state. The provider rejects an
incompatible Forge deployment before planning a mutation.

Rego modules and readable references are validated by the target Forge server
during planning. `terraform validate` and an offline
`terraform plan -refresh=false` prove only HCL/provider schema validity. A
connected saved plan validates references, policy semantics, revision, and
manager compatibility. Apply refreshes the short-lived signature and fails
without mutation if any validated fact changed.

## CI workflow

```bash theme={"system"}
terraform fmt -check
terraform init
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan
```

Pin the provider to a reviewed compatible minor line and commit the dependency
lock file. Upgrade by changing the version constraint, running
`terraform init -upgrade`, reviewing provider checksums and the complete plan,
and applying a saved plan. Do not combine a provider upgrade with unrelated
policy scope or action changes.

Run plans with one writer per state backend. Review policy deletions, authority
changes, scope expansion, stronger consequences, Rego source changes, and
gateway limits as security-sensitive changes.

## Troubleshooting

| Error                            | What to check                                                                      |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| Reference not found or ambiguous | Exact spelling, organization, directory qualification, and duplicates              |
| Authority conflict               | Claim resource, stable manager values, correct API organization, and current state |
| Revision conflict                | Refresh and review the remote change before replanning                             |
| Rego validation failed           | Package, fixed entrypoint, input fields, forbidden built-ins, and output schema    |
| Destroy rejected                 | Current revision, authority binding, `prevent_destroy`, and API permission         |