Getting Started

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 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.

In the Barndoor app, go to Settings → API Tokens.
Find the Terraform provider credentials panel and click Generate credential.
Choose a secret expiry (90 days by default; you can rotate at any time).
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:

main.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:

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:

main.tf

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

Step 4: Init, plan, apply

terraform init
terraform plan

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

terraform apply

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:

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

Step 6: Clean up

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 — before destroying anything you care about.

Next Steps

Manage MCP Access

Onboard an MCP server, connect it, and govern which AI Agents can use it.

Manage the LLM Gateway

Providers, model routing, access policies, rate limits, and budgets.

Manage Data Protection

Detection types, allow lists, and enforcement policies.

Best Practices

Importing, drift, CI/CD, and troubleshooting.

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.

Get Started

Use-Case Guides

Operations

Before You Begin

Step 1: Generate a provider credential

Step 2: Configure the provider

Step 3: Write your first resource

Step 4: Init, plan, apply

Step 5: Verify

Step 6: Clean up

Next Steps

Manage MCP Access

Manage the LLM Gateway

Manage Data Protection

Best Practices

Troubleshooting

​Before You Begin

​Step 1: Generate a provider credential

​Step 2: Configure the provider

​Step 3: Write your first resource

​Step 4: Init, plan, apply

​Step 5: Verify

​Step 6: Clean up

​Next Steps

Manage MCP Access

Manage the LLM Gateway

Manage Data Protection

Best Practices

​Troubleshooting

Before You Begin

Step 1: Generate a provider credential

Step 2: Configure the provider

Step 3: Write your first resource

Step 4: Init, plan, apply

Step 5: Verify

Step 6: Clean up

Next Steps

Troubleshooting