Terraform

The Toktra Terraform provider lets you manage your entire Toktra configuration as infrastructure-as-code. Policies, budgets, alert configs, SIEM connectors, ITSM connectors, and SSO settings are all supported resources.

Installing the provider

Add the Toktra provider to your Terraform configuration’s required_providers block:

versions.tf

terraform {
  required_providers {
    toktra = {
      source  = "toktra/toktra"
      version = "~> 1.0"
    }
  }
}

Run terraform init to download the provider:

terraform init

Authentication

Configure the provider with your Toktra API URL and API key:

provider.tf

provider "toktra" {
  api_url = "https://api.toktra.io"
  api_key = var.toktra_api_key
}

variable "toktra_api_key" {
  type      = string
  sensitive = true
}

You can also set these via environment variables — the provider reads TOKTRA_API_URL and TOKTRA_API_KEY automatically:

Environment variables

export TOKTRA_API_URL=https://api.toktra.io
export TOKTRA_API_KEY=your-api-key

Store your API key in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) and inject it at plan/apply time. Never commit API keys to version control.

Resources

`toktra_policy`

Manages a Toktra usage policy. Policies define conditions that trigger alerts or blocks.

policy.tf

resource "toktra_policy" "restrict_gpt4" {
  name        = "restrict-gpt4-to-engineering"
  type        = "model_restrict"
  severity    = "high"
  enabled     = true

  conditions = jsonencode({
    model      = "gpt-4"
    department = { not_in = ["engineering"] }
  })

  actions = jsonencode({
    action      = "alert"
    notify      = ["security@company.com"]
    slack_alert = true
  })
}

resource "toktra_policy" "daily_token_limit" {
  name     = "daily-token-limit-engineering"
  type     = "token_limit"
  severity = "high"
  enabled  = true

  conditions = jsonencode({
    max_tokens_per_day = 500000
    scope              = "per_user"
  })

  actions = jsonencode({
    action      = "warn_and_notify"
    notify      = ["eng-leads@company.com"]
    slack_alert = true
  })
}

Arguments:

Argument	Required	Description
`name`	Yes	Human-readable policy name
`type`	Yes	`token_limit`, `provider_block`, or `model_restrict`
`conditions`	Yes	JSON-encoded conditions object
`actions`	Yes	JSON-encoded actions object
`enabled`	No	Default `true`
`severity`	No	`low`, `medium`, `high`, or `critical`. Default `medium`

`toktra_budget`

Manages a monthly spending budget for your organization.

budget.tf

resource "toktra_budget" "engineering_monthly" {
  monthly_limit       = 10000.00
  alert_threshold_pct = 75
  rollover_enabled    = false
}

Arguments:

Argument	Required	Description
`monthly_limit`	Yes	Monthly spending limit in USD
`alert_threshold_pct`	No	Percentage that triggers an alert. Default `80`
`rollover_enabled`	No	Whether unused budget rolls over monthly. Default `false`

`toktra_alert_config`

Manages notification routing for Toktra alerts.

alert_config.tf

resource "toktra_alert_config" "security_critical" {
  name    = "Security — critical alerts"
  enabled = true

  channels = jsonencode([
    { type = "slack",   channel_id = "C12345678" },
    { type = "email",   address    = "security@company.com" },
    { type = "webhook", url        = "https://hooks.company.com/toktra" },
  ])

  severity_filter = ["high", "critical"]
}

Arguments:

Argument	Required	Description
`name`	Yes	Human-readable name
`channels`	Yes	JSON-encoded list of notification channel objects
`severity_filter`	No	List of severities to route. Omit to route all.
`enabled`	No	Default `true`

`toktra_siem_config`

Manages a SIEM connector (Splunk, Datadog, or Elasticsearch).

siem.tf

resource "toktra_siem_config" "splunk_prod" {
  name          = "Splunk Production"
  provider_type = "splunk"
  endpoint      = "https://splunk-hec.company.com:8088"
  is_active     = true

  credentials = jsonencode({
    token          = var.splunk_hec_token
    signing_secret = var.splunk_signing_secret
  })
}

resource "toktra_siem_config" "datadog" {
  name          = "Datadog"
  provider_type = "datadog"
  endpoint      = "https://http-intake.logs.datadoghq.com"
  is_active     = true

  credentials = jsonencode({
    api_key = var.datadog_api_key
  })
}

resource "toktra_siem_config" "elasticsearch" {
  name          = "Elasticsearch"
  provider_type = "elastic"
  endpoint      = "https://es.company.com:9200"
  is_active     = true

  credentials = jsonencode({
    api_key        = var.elastic_api_key
    signing_secret = var.elastic_signing_secret
  })
}

Arguments:

Argument	Required	Description
`name`	Yes	Human-readable name
`provider_type`	Yes	`splunk`, `datadog`, `elastic`, or `generic`
`endpoint`	Yes	SIEM endpoint URL
`credentials`	Yes	JSON-encoded credential object (marked sensitive)
`events_filter`	No	JSON-encoded event filter
`is_active`	No	Default `true`

`toktra_itsm_config`

Manages an ITSM connector (ServiceNow or Jira).

itsm.tf

resource "toktra_itsm_config" "jira" {
  name               = "Jira Cloud"
  provider_type      = "jira"
  instance_url       = "https://company.atlassian.net"
  default_project    = "SEC"
  default_issue_type = "Bug"
  is_active          = true

  credentials = jsonencode({
    email     = var.jira_email
    api_token = var.jira_api_token
  })
}

resource "toktra_itsm_config" "servicenow" {
  name               = "ServiceNow"
  provider_type      = "servicenow"
  instance_url       = "https://company.service-now.com"
  default_project    = "IT Security"
  default_issue_type = "Incident"
  is_active          = true

  credentials = jsonencode({
    username = var.snow_username
    password = var.snow_password
  })
}

Arguments:

Argument	Required	Description
`name`	Yes	Human-readable name
`provider_type`	Yes	`servicenow` or `jira`
`instance_url`	Yes	ITSM instance base URL
`credentials`	Yes	JSON-encoded credentials (marked sensitive)
`default_project`	No	Default Jira project key or ServiceNow assignment group
`default_issue_type`	No	Default issue type. Default `"Bug"`
`is_active`	No	Default `true`

`toktra_sso_config`

Manages SSO/SAML configuration for your organization.

sso.tf

resource "toktra_sso_config" "okta" {
  name          = "Okta SSO"
  provider_type = "okta"
  entity_id     = "https://company.okta.com/app/entity-id"
  sso_url       = "https://company.okta.com/app/sso/saml"
  certificate   = file("${path.module}/okta-cert.pem")
  enabled       = true
}

Arguments:

Argument	Required	Description
`name`	Yes	Human-readable name
`provider_type`	Yes	`okta`, `azure_ad`, `google`, `onelogin`, or `custom_saml`
`entity_id`	Yes	SAML entity ID (issuer)
`sso_url`	Yes	SSO login URL
`certificate`	Yes	PEM-encoded X.509 signing certificate (marked sensitive)
`enabled`	No	Default `true`

Complete example

The following configuration manages a full Toktra deployment:

main.tf

terraform {
  required_providers {
    toktra = {
      source  = "toktra/toktra"
      version = "~> 1.0"
    }
  }
}

provider "toktra" {
  api_url = "https://api.toktra.io"
  api_key = var.toktra_api_key
}

# Budget
resource "toktra_budget" "engineering_monthly" {
  monthly_limit       = 50000
  alert_threshold_pct = 80
  rollover_enabled    = false
}

# Policy — restrict GPT-4 to engineering
resource "toktra_policy" "restrict_gpt4" {
  name     = "restrict-gpt4-to-engineering"
  type     = "model_restrict"
  severity = "high"
  enabled  = true

  conditions = jsonencode({
    model      = "gpt-4"
    department = { not_in = ["engineering"] }
  })

  actions = jsonencode({
    action = "alert"
  })
}

# Alert routing
resource "toktra_alert_config" "security_team" {
  name    = "Security team alerts"
  enabled = true

  channels = jsonencode([
    { type = "slack", channel_id = "C12345678" },
    { type = "email", address    = "security@company.com" },
  ])

  severity_filter = ["high", "critical"]
}

# SIEM — Splunk
resource "toktra_siem_config" "splunk" {
  name          = "Splunk Production"
  provider_type = "splunk"
  endpoint      = "https://splunk-hec.company.com:8088"
  is_active     = true

  credentials = jsonencode({
    token          = var.splunk_hec_token
    signing_secret = var.siem_signing_secret
  })
}

# ITSM — Jira
resource "toktra_itsm_config" "jira" {
  name               = "Jira Cloud"
  provider_type      = "jira"
  instance_url       = "https://company.atlassian.net"
  default_project    = "SEC"
  default_issue_type = "Bug"
  is_active          = true

  credentials = jsonencode({
    email     = var.jira_email
    api_token = var.jira_api_token
  })
}

# SSO — Okta
resource "toktra_sso_config" "okta" {
  name          = "Okta SSO"
  provider_type = "okta"
  entity_id     = "https://company.okta.com/app/entity-id"
  sso_url       = "https://company.okta.com/app/sso/saml"
  certificate   = file("${path.module}/okta-cert.pem")
  enabled       = true
}

Importing existing resources

If you have existing Toktra resources created through the dashboard, import them into Terraform state using terraform import:

Import examples

# Import a policy by ID
terraform import toktra_policy.restrict_gpt4 <policy-uuid>

# Import a budget
terraform import toktra_budget.engineering_monthly <budget-uuid>

# Import a SIEM config
terraform import toktra_siem_config.splunk <siem-config-uuid>

# Import an ITSM config
terraform import toktra_itsm_config.jira <itsm-config-uuid>

# Import an SSO config
terraform import toktra_sso_config.okta <sso-config-uuid>

Find resource UUIDs in the Toktra dashboard under Integrations or via the Toktra API (GET /v1/api/siem/configs, etc.). After importing, run terraform plan to verify the imported state matches your configuration. Adjust any attribute values that differ before running terraform apply.

Importing a resource does not update the live Toktra resource. It only brings existing state into Terraform management. Run terraform apply after import to reconcile any configuration differences.

Get Started

Core Concepts

Agents & Extensions

Guides

Integrations

Security & Compliance

Installing the provider

Authentication

Resources

`toktra_policy`

`toktra_budget`

`toktra_alert_config`

`toktra_siem_config`

`toktra_itsm_config`

`toktra_sso_config`

Complete example

Importing existing resources

​Installing the provider

​Authentication

​Resources

​toktra_policy

​toktra_budget

​toktra_alert_config

​toktra_siem_config

​toktra_itsm_config

​toktra_sso_config

​Complete example

​Importing existing resources

Installing the provider

Authentication

Resources

`toktra_policy`

`toktra_budget`

`toktra_alert_config`

`toktra_siem_config`

`toktra_itsm_config`

`toktra_sso_config`

Complete example

Importing existing resources