## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.barndoor.ai/llms.txt)

Use this file to discover all available pages before exploring further.

This guide takes you from an empty directory to your first `terraform apply` against your Barndoor organization.

**Estimated time**: 10–15 minutes

## Before You Begin

You’ll need:

- A Barndoor account with **admin privileges** for your organization
- [Terraform](https://developer.hashicorp.com/terraform/install) 1.0 or later (OpenTofu works too)

## Step 1: Generate a provider credential

The provider authenticates as a machine credential scoped to your organization — no interactive login, no user tokens.

1. In the Barndoor app, go to **Settings → API Tokens**.
2. Find the **Terraform provider credentials** panel and click **Generate credential**.
3. Choose a **secret expiry** (90 days by default; you can rotate at any time).
4. Copy the three values from the reveal dialog: **Client ID**, **Client secret**, and **Organization ID**. The dialog also offers a ready-made Terraform configuration you can copy directly.

The **client secret is shown only once**. If you lose it, rotate the credential to get a fresh secret — the client ID stays the same.

**One credential is active per organization.** Rotating replaces the secret in place; revoking disables the credential entirely. If your team already uses Terraform with Barndoor, coordinate before rotating — a rotation invalidates the secret everyone else is using.

## Step 2: Configure the provider

Create a working directory with a `main.tf`:

```hcl
tf
terraform {
  required_providers {
    barndoor = {
      source  = "barndoor-ai/barndoor"
      version = "~> 0.3"
    }
  }
}

provider "barndoor" {
  # The platform host root, with no path — the provider appends each
  # service's API prefix itself.
  base_url  = "https://platform.barndoor.ai"
  token_url = "https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/token"

client_id       = "your-client-id"
  organization_id = "your-organization-id"

# client_secret is read from the BARNDOOR_CLIENT_SECRET environment
  # variable — never commit it to configuration.
}
```

Then export the secret:

```bash
export BARNDOOR_CLIENT_SECRET="the-secret-from-step-1"
```

Every provider argument has an environment-variable fallback, which is the recommended way to configure CI:

| Argument           | Environment variable       |
|--------------------|---------------------------|
| `base_url`        | `BARNDOOR_BASE_URL`      |
| `token_url`       | `BARNDOOR_TOKEN_URL`     |
| `client_id`       | `BARNDOOR_CLIENT_ID`     |
| `client_secret`   | `BARNDOOR_CLIENT_SECRET` |
| `organization_id` | `BARNDOOR_ORGANIZATION_ID` |

All five values are required — the provider fails with a clear error naming any that are missing.

`base_url` is the **platform host root with no path**. The provider appends each service’s API prefix itself, and rejects a `base_url` that carries a path suffix.

## Step 3: Write your first resource

We’ll create a data-protection allow-list entry — it has no dependencies, changes no runtime behavior beyond suppressing findings for one harmless literal, and is fully deleted on destroy. Add to `main.tf`:

```hcl
resource "barndoor_dlp_allow_list_entry" "quickstart" {
  pattern      = "docs.example.com"
  pattern_type = "PATTERN_TYPE_LITERAL"
  reason       = "Terraform quickstart — safe to delete"
}
```

Reference: [`barndoor_dlp_allow_list_entry`](https://registry.terraform.io/providers/barndoor-ai/barndoor/latest/docs/resources/dlp_allow_list_entry)

## Step 4: Init, plan, apply

```bash
tf
terraform init
terraform plan
```

The plan should show one resource to add. Apply it:

```bash
tf
terraform apply
```

```bash
barndoor_dlp_allow_list_entry.quickstart: Creating...
barndoor_dlp_allow_list_entry.quickstart: Creation complete after 1s

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
```

## Step 5: Verify

Two quick checks that everything is wired correctly:

1. Run `terraform plan` again — it should report `No changes`, confirming that what Terraform created matches what the platform stored.
2. In the Barndoor app, open **Data Control Center** and find the allow-list entry you just created.

## Step 6: Clean up

```bash
tf
terraform destroy
```

For this resource, destroy really deletes the entry. That is **not true of every resource**: destroying a `barndoor_policy` archives it, destroying an org-singleton like `barndoor_dlp_org_config` resets it to platform defaults, and destroying a `barndoor_mcp_server` tears down its connections. Check the resource’s Registry page — and see the [destroy semantics table](https://docs.barndoor.ai/terraform/best-practices#destroy-is-not-always-delete) — before destroying anything you care about.

## Troubleshooting

**Token request failed: invalid_client**  
The `client_id` / `client_secret` pair was rejected by the token endpoint. Confirm you exported `BARNDOOR_CLIENT_SECRET` in the shell running Terraform, and that the credential hasn’t been rotated (rotation invalidates the old secret) or revoked.

**403 errors mentioning the organization admin role**  
The credential exists but isn’t authorized for the operation. This usually means `organization_id` doesn’t match the organization the credential was generated in — copy it from the credential panel in **Settings → API Tokens** rather than from elsewhere.

**base_url must be the platform host root**  
The provider rejects a `base_url` with a path suffix (for example a trailing `/api`). Use the bare origin, e.g. `https://platform.barndoor.ai`.

**The provider block validates but apply hangs or times out**  
Check that `base_url` and `token_url` are reachable from the machine running Terraform — corporate proxies and VPNs are the usual cause. The provider uses plain HTTPS with a 30-second timeout per request.