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

# Getting Started

> Generate a provider credential, configure the Barndoor Terraform provider, and apply your first resource

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

> [!NOTE]
>
> **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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> **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 main.tf theme={null}
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 theme={null}
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.

> [!WARNING]
>
> `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 main.tf theme={null}
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 theme={null}
terraform init
terraform plan
```

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

```bash theme={null}
terraform apply
```

```text theme={null}
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 theme={null}
terraform destroy
```

> [!WARNING]
>
> 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.md#destroy-is-not-always-delete) — before destroying anything you care about.

## Next Steps

> [card] [Manage MCP Access](https://docs.barndoor.ai/terraform/manage-mcp-access.md)
>
> Onboard an MCP server, connect it, and govern which AI Agents can use it.

> [card] [Manage the LLM Gateway](https://docs.barndoor.ai/terraform/llm-gateway.md)
>
> Providers, model routing, access policies, rate limits, and budgets.

> [card] [Manage Data Protection](https://docs.barndoor.ai/terraform/data-protection.md)
>
> Detection types, allow lists, and enforcement policies.

> [card] [Best Practices](https://docs.barndoor.ai/terraform/best-practices.md)
>
> Importing, drift, CI/CD, and troubleshooting.

## Troubleshooting

> [accordion] 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.

> [accordion] 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.

> [accordion] 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`.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.