> ## 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.

# Terraform

> Manage Toktra policies, budgets, alerts, and integrations as code with the official Terraform provider.

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:

```hcl title="versions.tf" theme={null}
terraform {
  required_providers {
    toktra = {
      source  = "toktra/toktra"
      version = "~> 1.0"
    }
  }
}
```

Run `terraform init` to download the provider:

```bash theme={null}
terraform init
```

***

## Authentication

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

```hcl title="provider.tf" theme={null}
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:

```bash title="Environment variables" theme={null}
export TOKTRA_API_URL=https://api.toktra.io
export TOKTRA_API_KEY=your-api-key
```

<Tip>
  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.
</Tip>

***

## Resources

### `toktra_policy`

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

```hcl title="policy.tf" theme={null}
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.

```hcl title="budget.tf" theme={null}
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.

```hcl title="alert_config.tf" theme={null}
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).

```hcl title="siem.tf" theme={null}
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).

```hcl title="itsm.tf" theme={null}
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.

```hcl title="sso.tf" theme={null}
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:

```hcl title="main.tf" theme={null}
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`:

```bash title="Import examples" theme={null}
# 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`.

<Warning>
  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.
</Warning>