🔧 Funnel as Code is still in initial development

Functionality is still being refined and added which means the steps and features in this article will evolve.

Why use it?

You have many data sources and want consistent naming, structure, and ownership
You want consistent setup across multiple workspaces
You need an audit trail for configuration changes
Multiple people collaborate and you want reviewable changes
You want to bootstrap new workspaces quickly from a known baseline

Challenge without code	How Funnel as Code solves it
Scaling: Setting up 50+ connectors manually takes hours	Define once, deploy to many workspaces in seconds
Review: No audit trail of who changed what and when	Every change is tracked in version control (Git)
Automate: Reproducing a setup in a new workspace is tedious	Copy the configuration file and apply it
Standardize: Hard to enforce consistency across teams/clients	Share templates that guarantee identical setups
Version control: Rolling back a broken change means manual fixing	Revert to a previous version with one command

How it works (concepts)

You write Funnel configuration as code (Terraform files)
Terraform produces a “plan” (what it intends to change)
You review the plan (locally or in CI)
You apply the plan to update your Funnel workspace

Key terms

Term	Description
Terraform	A tool designed to manage Infrastructure as Code (IaC) that compares “desired state” (your code) with “current state” (Funnel) and makes the necessary updates.
Provider	The Terraform plugin that talks to Funnel.
Workspace	The Funnel workspace you’re configuring.
Connection	Credentials + connector + scope (used by Terraform via a stable ID).
Data source	A source you connect in Funnel (e.g., Google Ads, TikTok).
Fields	How Funnel structures/normalizes data (schema, mappings, etc.).
State	Terraform keeps track of what it has created in a state file to know the difference between "create something new" and "update something that already exists.
System user	A machine identity (client ID + secret) used by external platforms (such as Terraform) to authenticate with Funnel on behalf of your subscription.

What you’ll set up

By the end of this guide you should be able to:

Authenticate Terraform to your Funnel workspace
Create (or reference) a Connection
Create a Funnel data source from Terraform
Run Terraform safely (plan/apply)
Adopt a workflow that matches your team’s technical level

Quick start

Prerequisites

Have the Funnel as Code feature enabled for your subscription (Talk to Support)
Access to a Funnel workspace where you’re allowed to creating data sources
Access to the specific platform credentials for the platforms you'd like to manage through Terraform. (Credential management is still in development, please see step 6)

Step 1: Install Terraform

Install Terraform using your preferred method (e.g., package manager or official downloads).

Verify:

terraform -version

Step 2: Create a new project folder

Example structure:

funnel-setup/ 	
    terraform/ 		
        main.tf 		
        variables.tf 		
        versions.tf 		
        # optional: keep per-workspace variables in separate files 		    
        workspace-a.tfvars 		
        workspace-b.tfvars

Step 3: Configure the Funnel provider

In versions.tf define Terraform requirements and the Funnel provider. (Provider: https://registry.terraform.io/providers/funnel-io/funnel/0.2.0)

terraform { 	
    required_version = ">= 1.5.0" 	
    required_providers { 		
        funnel = { 			
            source  = "funnel-io/funnel" 			
            version = ">= 0.0.0" 		
        } 	
    }
}

In main.tf configure authentication (example pattern):

variable "client_id" {
  description = "Funnel Client ID"
  type        = string
  sensitive   = true
}

variable "client_secret" {
  description = "Funnel Client Secre"
  type        = string
  sensitive   = true
}

provider "funnel" {
  environment     = "us"
  subscription_id = "your_subscription_id_here"
  client_id       = var.client_id
  client_secret   = var.client_secret
}

Is our subscription in the US or EU environment?

Funnel gives customers the option to store their data either in Europe or in the US. By default, customer subscriptions are created in the US environment unless the EU environment has been explicitly requested.

You can check which environment your subscription is using by looking at your Funnel URL when logged in:

https://app.funnel.io/ = us environment
https://app.eu.funnel.io/ = eu environment

From your Terraform directory:

terraform init

Step 4: Authenticate to Funnel

You will need a machine-to-machine authentication method provided for Funnel as Code, called a System user. See provider docs:

To find/create an System user:

Ensure the Funnel as Code feature is enabled for your subscription (contact Funnel Support).
Your user has the role Subscription Administrator (or higher).
Go to Subscription settings > Users > System users
Create a new System user and copy its Client ID and Client Secret into Terraform.
Set these credentials as environment variables on your machine (and in CI).

Example:

export TF_VAR_client_id="EXAMPLE_CLIENT_ID" 
export TF_VAR_client_secret="EXAMPLE_CLIENT_SECRET"

Alternatively, you can pass input variables on the command line (e.g. for local testing). See Terraform docs: https://developer.hashicorp.com/terraform/cli/commands/plan#input-variables-on-the-command-line

Example:

terraform plan \
  -var="client_id=..." \
  -var="client_secret=..." \
  -var="subscription_id=..."

Step 5: Create a new workspace (recommended)

Before applying configuration to a production workspace, we recommend creating a separate test workspace first.

Why:

It demonstrates the end-to-end workflow (plan/apply) in a safe environment
It helps you validate permissions, credentials, and CI setup before touching production

Create a workspace using Terraform (resource docs: https://registry.terraform.io/providers/funnel-io/funnel/latest/docs/resources/workspace):

resource "funnel_workspace" "my_sandbox" {
	name = "My sandbox"
}

Then run:

terraform plan 
terraform apply

Step 6: Create a data source

🔧 Sharing platform/source credentials with the system user is currently work in progress

To share platform credentials with the System user, you will currently need to contact Funnel Support which can then securely hand the credential ID needed for the specific connections to work.

This method is temporary and more functionality around sharing credentials will be introduced.

Once you have the credential ID for the platform you'd like to manage, create a Terraform resource that references the connection ID and connector-specific offering/account identifiers. Resource docs: https://registry.terraform.io/providers/funnel-io/funnel/latest/docs/resources/data_source

Example (illustrative only, update to match your connector and offering):

resource "funnel_data_source" "adwords_campaign" {
  workspace     = var.workspace_id
  type          = "adwords"
  name          = "Google Ads - Main Account"
  report_type   = "campaign"
  remote_id     = "12345678"
  credential_id = var.google_ads_credential_id
}

Step 7: Plan and apply

First preview changes:

terraform plan

Then apply:

terraform apply

Best practices

Store secrets in a secret manager (not in Git)
Restrict access to who can apply changes in CI
Version control + change review
- Keep Funnel setup code in Git
- Use pull requests for review

FAQ

Can I use Claude or any other AI to help me manage Terraform?

Yes:
Terraform agent skills to work with AI tooling

Terraform MCP

Terraform says it wants to recreate things unexpectedly

Verify you’re targeting the correct workspace
Ensure you’re using the correct Credential IDs
Compare the plan output to what exists in Funnel

Can Terraform create credentials / do OAuth automatically?

Not in the current beta. Connections must still be created via the regular Funnel browser interface. Terraform references the resulting stable Credential ID.

The self-serve interface for a Funnel user to obtain the Credential ID is still in development. To obtain the Credential ID, contact the Funnel product team.

Is this only for engineers?

No, but it might be a bit more technical than the traditional Funnel interface. Teams often start by having one person set it up, then give others a safe, repeatable process without needing deep Terraform knowledge.

Does Funnel as Code handle user provisioning?

No. Funnel as Code focuses on configuring Funnel setup.

For automated user provisioning into Funnel, Funnel supports SCIM user provisioning: https://help.funnel.io/en/articles/13396822-user-provisioning-with-scim

Can the system user see my credential contents?

No. Sharing a credential with a system user only grants the system user the ability to reference the credential (for example, by using the Credential ID in Terraform). The system user cannot view or extract the credential contents.

Shared credentials can be revoked at any time.

How do I get platform credentials from someone else?

In development: If someone else holds the platform credentials, you can either ask them to share their credential with your system user, or use Funnel’s credential request flow: https://help.funnel.io/en/articles/9479697-requesting-credentials-from-a-non-funnel-user

After you receive the credentials, you can either:

Add them to My credentials, then share them with the system user, or
Ask the person who has the credentials to share them directly with the system user

What parts of Funnel can I configure?

This will expand over time. Today the focus is on programmatic creation and management of setup entities such as workspaces, data sources, exports, and fields (scope depends on your release/beta access). Relevant docs:

Provider documentation: https://registry.terraform.io/providers/funnel-io/funnel/latest/docs

Requesting credentials from a non-Funnel user

How to request Digistore24 data in Funnel

Stay AI: Dimensions and metrics

User provisioning with SCIM

Connect Funnel MCP to Claude as a custom connector