---
type: how-to
title: Use Terraform or OpenTofu
summary: Manage Caputchin as infrastructure-as-code with the official provider, which works identically on Terraform and OpenTofu, with a worked example and a link to the full registry reference.
---

The official Caputchin provider lets you manage your account as infrastructure-as-code: declare troops, site keys, security policy, members, and tokens in `.tf` files and apply them like any other resource. It is the same management API as everything else under [automation](/docs/automation/management-api), expressed as Terraform resources.

It is published once and works with **both Terraform and OpenTofu** from the same source; the HCL is identical, only the CLI binary (`terraform` or `tofu`) and the registry differ. Everywhere below, use whichever you run.

## Mint an access token [#mint-an-access-token]

The provider reads its token from the `CAPUTCHIN_MANAGEMENT_TOKEN` environment variable (recommended, so it stays out of source). Either kind of token works (see [API authentication](/docs/automation/management-api#mint-an-access-token)): a [personal access token](/docs/account-management/personal-access-token) for full-account infrastructure, or a [troop access token](/docs/troops/tokens) scoped to the troops your configuration manages.

```bash
export CAPUTCHIN_MANAGEMENT_TOKEN=cpt_pat_...
```

There is a chicken-and-egg case: the provider can also *mint* tokens (the `caputchin_account_token` and `caputchin_troop_pat` resources), but it needs a token to authenticate in the first place. Mint the first one by hand in the dashboard, then let Terraform manage the rest.

## Configure the provider

```hcl
terraform {
  required_providers {
    caputchin = {
      source  = "caputchin/caputchin"
      version = "~> 0.1"
    }
  }
}

# Token from CAPUTCHIN_MANAGEMENT_TOKEN; endpoint defaults to https://api.caputchin.com.
provider "caputchin" {}
```

The same `source = "caputchin/caputchin"` resolves from the Terraform Registry and the OpenTofu Registry, so the block is the same under either tool.

## A worked example: a troop with a gated site key

This creates a troop, a site key in it, and turns on the game gate for that key:

```hcl
resource "caputchin_troop" "shop" {
  name = "shop-team"
}

resource "caputchin_site_key" "shop_frontend" {
  name     = "shop-frontend"
  troop_id = caputchin_troop.shop.id
}

resource "caputchin_site_security_settings" "shop_frontend" {
  site_id      = caputchin_site_key.shop_frontend.id
  require_game = true
}

# The public key is an attribute; the secret is sensitive, in state only.
output "shop_site_key" {
  value = caputchin_site_key.shop_frontend.key
}
```

Then, with either tool:

```bash
terraform init && terraform apply
# or
tofu init && tofu apply
```

The site key's `secret` is a sensitive computed attribute; read it from state (`terraform output`) to configure your [backend verification](/docs/integration-guides/verify-on-your-backend). Every apply is attributed to your token in the [audit log](/docs/audit-logs/overview) on Apex, so a change through Terraform is as traceable as a dashboard edit.

## What you can manage

Resources cover the same surface as the dashboard: troops and their members and tokens, site keys, security settings, hosted verification, game and white-label customization, and account tokens. Data sources let you read existing troops, sites, account info, and statistics into a configuration.

## The full reference

Every resource and data source, with all its arguments and attributes and import syntax, is on the provider's registry page. It is generated from the provider source, so it tracks the released version exactly:

- Terraform Registry: `registry.terraform.io/providers/caputchin/caputchin`
- OpenTofu Registry: `search.opentofu.org/provider/caputchin/caputchin`

For the underlying operations each resource performs, see the [interactive API reference](/docs/api-reference).

## See also

- [Manage Caputchin from the API](/docs/automation/management-api): the HTTP API the provider sits on.
- [Use the MCP server](/docs/automation/mcp): the AI-agent surface.
- [Troops](/docs/troops/overview) and [site keys](/docs/site-keys/overview): the resources you are managing.