Authentication

The Onehouse provider authenticates to the Onehouse control plane using environment variables — there is no .tf-based credential block. This is intentional: it prevents accidentally committing secrets to git and keeps credential rotation a CI/operator concern, not a code change.

Required environment variables

All five must be set before running terraform plan or terraform apply.

Env var	Purpose	Where to find it
ONEHOUSE_PROJECT_UID	x-onehouse-project-uid header. Identifies which Onehouse project to target.	Onehouse console → Profile → "Project ID"
ONEHOUSE_API_KEY	x-onehouse-api-key header (sensitive).	Onehouse console → Profile → "Service Principal API Key"
ONEHOUSE_API_SECRET	x-onehouse-api-secret header (sensitive).	Onehouse console → Profile → "Service Principal API Secret"
ONEHOUSE_LINK_UID	x-onehouse-link-uid header. Links the request to your data plane.	Onehouse console → Profile → "RequestID"
ONEHOUSE_REGION	x-onehouse-region header (e.g. us-west-2).	Region of your Onehouse data plane

warning

ONEHOUSE_API_KEY and ONEHOUSE_API_SECRET are credentials. Never commit them to git, paste them into chat/issues, or check them into .tf files. For CI, use your CI system's secret store (e.g. GitHub Actions secrets, AWS Secrets Manager).

Optional environment variables

Env var	Default	Purpose
ONEHOUSE_ACCOUNT_UID	Auto-derived from service principal	x-onehouse-account-uid header. Set explicitly only for multi-account setups.
ONEHOUSE_ENDPOINT	Derived from onehouse_control_plane provider arg	Override the API endpoint. Set this for staging/dev (e.g. https://staging-api.onehouse.ai).
ONEHOUSE_TIMEOUT	30m (or timeout in provider block)	Per-operation timeout. Go duration string (45m, 1h).

Control-plane selection

The provider talks to the Onehouse AWS control plane by default. Switch to GCP via the provider block:

provider "onehouse" {
  onehouse_control_plane = "gcp"
}

Endpoint resolution:

onehouse_control_plane	Resolved endpoint
"aws" (default)	https://api.onehouse.ai
"gcp"	https://api-gcp.onehouse.ai

ONEHOUSE_ENDPOINT (if set) overrides both — useful for staging/dev environments.

Example: full shell setup

# Production AWS
export ONEHOUSE_PROJECT_UID=proj_abc123
export ONEHOUSE_API_KEY=key_xxxxxxxxxxxxx
export ONEHOUSE_API_SECRET=secret_yyyyyyyyyyy
export ONEHOUSE_LINK_UID=link_zzzzzzzzz
export ONEHOUSE_REGION=us-west-2

terraform plan

Example: 1Password CLI integration

If you store credentials in 1Password, fetch them into env vars without ever putting them in a shell history file:

export ONEHOUSE_PROJECT_UID=$(op read "op://Onehouse/Project UID/credential")
export ONEHOUSE_API_KEY=$(op read "op://Onehouse/API Key/credential")
export ONEHOUSE_API_SECRET=$(op read "op://Onehouse/API Secret/credential")
export ONEHOUSE_LINK_UID=$(op read "op://Onehouse/Link UID/credential")
export ONEHOUSE_REGION=us-west-2

terraform plan

Example: GitHub Actions

- name: Terraform Apply
  env:
    ONEHOUSE_PROJECT_UID: ${{ secrets.ONEHOUSE_PROJECT_UID }}
    ONEHOUSE_API_KEY:     ${{ secrets.ONEHOUSE_API_KEY }}
    ONEHOUSE_API_SECRET:  ${{ secrets.ONEHOUSE_API_SECRET }}
    ONEHOUSE_LINK_UID:    ${{ secrets.ONEHOUSE_LINK_UID }}
    ONEHOUSE_REGION:      us-west-2
  run: |
    terraform init
    terraform apply -auto-approve

Verifying credentials work

A quick way to confirm everything's wired:

terraform init
echo 'data "onehouse_cluster" "test" { name = "any-existing-cluster-name" }' > test.tf
terraform plan

If credentials are valid, the plan succeeds even if the cluster does not exist (the data source errors with "not found" rather than an authentication failure).

Common authentication failures are documented in Troubleshooting.