Skip to main content
The official Terraform provider manages KnoxCall resources as code through the /v1 Management API. Built with the Terraform Plugin Framework.

​
Resources

ResourceCRUDImport
knoxcall_routeYesYes (id)
knoxcall_secretYesYes (id)
knoxcall_clientYesYes (id)
knoxcall_webhookYesYes (id)

​
Provider configuration

terraform {
  required_providers {
    knoxcall = {
      source = "knoxcall/knoxcall"
    }
  }
}

provider "knoxcall" {
  # Defaults to https://api.knoxcall.com (or $KNOXCALL_BASE_URL).
  base_url = "https://api.knoxcall.com"

  # A tenant API key (tk_…) or OAuth token (kc_…). Sent as Authorization: Bearer.
  # Prefer the KNOXCALL_API_KEY environment variable over committing this.
  api_key = var.knoxcall_api_key
}
Not yet published to the Terraform Registry — until it is, build from the monorepo (sdk/knoxcall-terraform) and point Terraform at the local binary with a dev_overrides block in ~/.terraformrc.

​
Example

resource "knoxcall_route" "weather" {
  name            = "weather-api"
  target_base_url = "https://api.weatherapi.com"
}

resource "knoxcall_secret" "weather_key" {
  name  = "weather-api-key"
  value = var.weather_api_key # Sensitive; never read back from the server
}

resource "knoxcall_client" "backend" {
  name       = "backend-service"
  type       = "server"
  ip_address = "203.0.113.10"
}

resource "knoxcall_webhook" "alerts" {
  name        = "request-errors"
  url         = "https://hooks.example.com/knoxcall"
  event_types = ["request.server_error", "request.timeout"]
}

output "route_id" {
  value = knoxcall_route.weather.id
}

​
Sensitive state

  • knoxcall_secret.value is write-only server-side — GET returns metadata, never the value — so Read keeps the value from state instead of diffing it. Rotations you make outside Terraform will not show as drift.
  • knoxcall_webhook.secret_key is returned exactly once at create and preserved in state (marked Sensitive) across refreshes.
  • The provider’s api_key is Sensitive in the schema and never appears in errors, logs, or diagnostics.
Both values live in your Terraform state file. Treat the state as a secret: use an encrypted remote backend and restrict access accordingly.

​
Import

All four resources import by id (the resource’s UUID): 
terraform import knoxcall_route.weather <route-uuid>

​
Behavior

The provider’s API client follows the SDK parity standard where applicable:
  • Retries: 408/429/500/502/503/504 retried up to 3 attempts with half-jitter exponential backoff (100ms base, 5s cap). 409 is never retried. On 429 a server Retry-After is honored, capped at 30s.
  • Idempotency: every mutating request carries a ULID X-Idempotency-Key generated once per logical request — stable across retries, so transport failures are also safe to retry.
  • 401: fails fast with a clear diagnostic (the credential is a static api_key, so there is nothing to re-mint).
  • Cancellation: all requests and retry backoffs respect Terraform’s operation context — interrupts abort promptly.

​
Full reference

Local build instructions and dev_overrides setup: sdk/knoxcall-terraform/README.md in the monorepo.