Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt

Use this file to discover all available pages before exploring further.

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:
ArgumentRequiredDescription
nameYesHuman-readable policy name
typeYestoken_limit, provider_block, or model_restrict
conditionsYesJSON-encoded conditions object
actionsYesJSON-encoded actions object
enabledNoDefault true
severityNolow, 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:
ArgumentRequiredDescription
monthly_limitYesMonthly spending limit in USD
alert_threshold_pctNoPercentage that triggers an alert. Default 80
rollover_enabledNoWhether 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:
ArgumentRequiredDescription
nameYesHuman-readable name
channelsYesJSON-encoded list of notification channel objects
severity_filterNoList of severities to route. Omit to route all.
enabledNoDefault 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:
ArgumentRequiredDescription
nameYesHuman-readable name
provider_typeYessplunk, datadog, elastic, or generic
endpointYesSIEM endpoint URL
credentialsYesJSON-encoded credential object (marked sensitive)
events_filterNoJSON-encoded event filter
is_activeNoDefault 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:
ArgumentRequiredDescription
nameYesHuman-readable name
provider_typeYesservicenow or jira
instance_urlYesITSM instance base URL
credentialsYesJSON-encoded credentials (marked sensitive)
default_projectNoDefault Jira project key or ServiceNow assignment group
default_issue_typeNoDefault issue type. Default "Bug"
is_activeNoDefault 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:
ArgumentRequiredDescription
nameYesHuman-readable name
provider_typeYesokta, azure_ad, google, onelogin, or custom_saml
entity_idYesSAML entity ID (issuer)
sso_urlYesSSO login URL
certificateYesPEM-encoded X.509 signing certificate (marked sensitive)
enabledNoDefault 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.