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

# Manage Bronto with Terraform

> Use the official Bronto Terraform provider to manage Bronto resources and query existing configuration as code.

The official Bronto Terraform provider lets you version, review, and deploy Bronto configuration alongside the rest of your infrastructure.

Use this guide to configure the provider and manage your first Bronto resource. For every available argument and exported attribute, use the [provider reference in the Terraform Registry](https://registry.terraform.io/providers/brontoio/bronto/latest/docs).

> **[Terraform Registry](https://registry.terraform.io/providers/brontoio/bronto/latest/docs)**
>
> Browse the generated provider, resource, and data source reference.

> **[GitHub repository](https://github.com/brontoio/terraform-provider-bronto)**
>
> View the provider source, examples, and release history.

> [!NOTE]
>
> Use the latest provider release. The examples on this page require `v0.3.1` or later; run `terraform init -upgrade` to update the version selected in your dependency lock file.

## What you can manage

The provider supports these Bronto resources:

| Resource | Use it to |
| - | - |
| [`bronto_user`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/resources/user) | Create and manage Bronto users and their roles |
| [`bronto_dashboard`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/resources/dashboard) | Create and manage dashboards |
| [`bronto_widget`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/resources/widget) | Define dashboard widgets |
| [`bronto_metric_definition`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/resources/metric_definition) | Create saved metric definitions |
| [`bronto_slack_integration`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/resources/slack_integration) | Configure Slack notification integrations |
| [`bronto_webhook_integration`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/resources/webhook_integration) | Configure webhook notification integrations |

The provider also includes these data sources:

| Data source | Use it to |
| - | - |
| [`bronto_dataset`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/data-sources/dataset) | Look up a dataset by ID or by its collection and dataset name |
| [`bronto_slack_workspaces`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/data-sources/slack_workspaces) | List Slack workspaces already connected to the organisation |
| [`bronto_user`](https://registry.terraform.io/providers/brontoio/bronto/latest/docs/data-sources/user) | Look up an existing user by ID or email |

## Prerequisites

Before you begin, you need:

* Terraform `1.5` or later
* A Bronto API endpoint, such as `https://api.eu.bronto.io`
* A Bronto API key with write permission for the resources you want to manage

For an initial evaluation of the full provider, use an Admin API key. For ongoing use, create a dedicated key with only the permissions required by your configuration. See [API Keys](https://docs.bronto.io/Account-Management/API-Keys.md) for instructions.

## Configure the provider

**1. Declare the provider**

Create a Terraform configuration that uses the latest provider release. The minimum version below includes data sources and provider-level default tags introduced after the initial release:

```hcl main.tf theme={"dark"}
terraform {
  required_version = ">= 1.5"

  required_providers {
    bronto = {
      source  = "brontoio/bronto"
      version = ">= 0.3.1"
    }
  }
}

variable "bronto_endpoint" {
  description = "Base URL for the Bronto API"
  type        = string
  default     = "https://api.eu.bronto.io"
}

variable "bronto_api_key" {
  description = "API key used to manage Bronto resources"
  type        = string
  sensitive   = true
}

provider "bronto" {
  endpoint = var.bronto_endpoint
  api_key  = var.bronto_api_key

  default_tags = {
    managed_by = "terraform"
  }
}
```

Change `bronto_endpoint` if your organisation uses another Bronto region or environment. `default_tags` are merged into every taggable `bronto_user`, `bronto_dashboard`, and `bronto_widget`; tags set directly on a resource take precedence.

**2. Provide the API key securely**

Pass the API key through an environment variable rather than writing it into a committed `.tf` or `.tfvars` file:

```bash theme={"dark"}
export TF_VAR_bronto_api_key="<YOUR_API_KEY>"
```

The provider also supports the `BRONTO_ENDPOINT` and `BRONTO_API_KEY` environment variables. In CI, inject credentials from your platform's secret store.

**3. Declare a Bronto resource**

Add a user resource to the configuration:

```hcl main.tf theme={"dark"}
resource "bronto_user" "example" {
  first_name = "Jane"
  last_name  = "Doe"
  email      = "jane.doe@example.com"
  roles      = ["Standard"]
}
```

> [!WARNING]
>
> Applying this example creates a real Bronto user and may send an invitation email. Replace the example address with an address you control.

**4. Review and apply the change**

Initialise Terraform, validate the configuration, and review the plan before applying it:

```bash theme={"dark"}
terraform init
terraform fmt
terraform validate
terraform plan
terraform apply
```

Commit the generated `.terraform.lock.hcl` file so every environment uses the same provider build.

## Manage multiple organisations

Declare an aliased provider for each organisation when a root organisation and its child organisations use different API keys. Then select the correct provider on every resource. Users belong to the root organisation, so manage `bronto_user` resources with the root provider.

```hcl main.tf theme={"dark"}
provider "bronto" {
  alias    = "root"
  endpoint = var.bronto_endpoint
  api_key  = var.root_org_api_key
}

provider "bronto" {
  alias    = "child"
  endpoint = var.bronto_endpoint
  api_key  = var.child_org_api_key
}

resource "bronto_user" "root_user" {
  provider = bronto.root

  first_name = "Jane"
  last_name  = "Doe"
  email      = "jane.doe@example.com"
  roles      = ["Standard"]
}

resource "bronto_dashboard" "child_dashboard" {
  provider = bronto.child

  name = "Child organisation overview"
}
```

Use a separate API key for each organisation and store every key independently. For more information about the organisation model, see [Multi-Organisation](https://docs.bronto.io/Account-Management/Multi-Org.md).

## Recommended workflow

* Run `terraform fmt` and `terraform validate` on every change.
* Run `terraform plan` in pull requests and require review before `terraform apply`.
* Run `terraform init -upgrade`, then review and commit the updated `.terraform.lock.hcl`, when adopting a newer provider release.
* Use separate state and API keys for development, staging, and production.
* Avoid editing a Terraform-managed resource in both the Bronto UI and Terraform, because the next apply can replace the manual change.
* Review a destroy plan carefully. Removing a resource from configuration can delete the corresponding resource in Bronto.
* Refer to the [Terraform Registry](https://registry.terraform.io/providers/brontoio/bronto/latest/docs) for the current schemas and examples instead of copying schema details into your own documentation.

## Troubleshooting

### Authentication fails

Confirm that the API key is active and has permission to read and write every resource in the configuration. Check that the key and endpoint belong to the same Bronto region and organisation.

### Terraform manages the wrong organisation

When you use provider aliases, add `provider = bronto.<alias>` to each resource. Terraform otherwise uses the default, unaliased provider configuration.

### A plan shows unexpected changes

Check whether the resource was changed in the Bronto UI after the last apply. Review the generated plan before reconciling the configuration or applying the change.


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