Repository Public
1# Model, tool, and data controls with Terraform23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Use this guide to apply model, hosted-tool, and data-retention controls to an existing project. These controls determine what project workloads can use and which approved retention policy applies. They don't grant users or service accounts access to the project.67After completing the main workflow, you will have a repeatable configuration that:89- Limits the project to an approved set of models.10- Sets an explicit permission for every supported hosted tool.11- Applies the organization's default data-retention policy to the project.1213## Before you begin1415Complete the [Terraform provider setup](https://developers.openai.com/api/docs/guides/terraform) and export an Admin API key as `OPENAI_ADMIN_KEY`. You also need:1617- The ID of an existing project.18- The IDs of models available to your organization.19- An organization with data-retention controls enabled if you plan to manage project retention.2021Use a test project when evaluating the workflow. To disable a hosted tool for one project, the organization-level tool policy must already limit that tool to selected projects. A project can't disable a tool that the organization has enabled for every project.2223## Restrict model access2425`openai_project_model_permissions` applies either an allowlist or a list of denied models to one project. This example permits only `gpt-5.4-mini`:2627```terraform28resource "openai_project_model_permissions" "application" {29 project_id = "proj_123"30 mode = "allow_list"31 model_ids = ["gpt-5.4-mini"]32}33```3435Set `mode` to:3637- `allow_list` to permit only the models in `model_ids`.38- `deny_list` to permit available models except those in `model_ids`.3940Each model ID must be visible to the organization. This includes any fine-tuned model snapshots that you add to the policy. Terraform reconciles changes to the mode and model list during the next plan and apply.4142## Configure hosted tools4344`openai_project_hosted_tool_permissions` manages five project-level tool permissions. Set every field so the reviewed configuration describes the complete policy:4546```terraform47resource "openai_project_hosted_tool_permissions" "application" {48 project_id = "proj_123"49 file_search_enabled = true50 web_search_enabled = false51 image_generation_enabled = false52 mcp_enabled = false53 code_interpreter_enabled = true54}55```5657The fields control file search, web search, image generation, remote MCP servers, and Code Interpreter. Each organization's hosted-tool policy has three modes: allow all projects, deny all projects, or allow selected projects. Setting a field to `true` permits that tool for the project, subject to the organization's other eligibility and retention requirements. Setting a field to `false` removes the project from that tool's selected-project policy. If the organization currently allows the tool for all projects, setting the field to `false` fails. Change the organization's tool policy to allow selected projects before disabling the tool for an individual project.5859Terraform refreshes all five values from OpenAI and reports dashboard changes as drift on the next plan.6061## Configure data retention6263`openai_project_data_retention` applies an approved retention type to one project. Inherit the organization's current policy unless the project has an approved override:6465```terraform66resource "openai_project_data_retention" "application" {67 project_id = "proj_123"68 type = "organization_default"69}70```7172The provider also accepts `none`, `zero_data_retention`, `modified_abuse_monitoring`, `enhanced_zero_data_retention`, and `enhanced_modified_abuse_monitoring`. The available modes and permitted transitions depend on your organization's configuration and the project's data-residency region.7374Review [Your data](https://developers.openai.com/api/docs/guides/your-data) and your organization's OpenAI agreement before selecting a project override.7576### Manage the organization default7778Use `openai_organization_data_retention` only when Terraform owns the existing organization-level setting:7980```terraform81resource "openai_organization_data_retention" "default" {82 type = "zero_data_retention"83}84```8586This resource changes an existing organization setting; it doesn't enroll an organization in a data-retention program. Some transitions require support or aren't available between retention tiers.8788Removing `openai_project_hosted_tool_permissions` or89 `openai_project_data_retention` from configuration removes the resource from90 Terraform state but leaves the remote settings unchanged. Removing91 `openai_project_model_permissions` deletes the project's model-permission92 configuration. Review destroy plans with these different behaviors in mind.9394## Detect changes outside Terraform9596Run a plan to refresh remote state and compare it with the reviewed configuration:9798```bash99terraform plan -detailed-exitcode100```101102Exit code `0` means no changes, `2` means the plan contains changes, and `1` means Terraform encountered an error. Investigate unexpected changes before applying. Don't automatically overwrite an emergency administrative change without first understanding its purpose.103104## Run the complete example105106The following example manages all three project controls together. Create `main.tf`:107108```terraform109terraform {110 required_version = ">= 1.0"111112 required_providers {113 openai = {114 source = "openai/openai"115 version = ">= 1.0.0"116 }117 }118}119120provider "openai" {}121122variable "project_id" {123 type = string124 description = "ID of the existing OpenAI project."125}126127variable "model_permission_mode" {128 type = string129 description = "Whether model_ids is an allowlist or denylist."130 default = "allow_list"131132 validation {133 condition = contains(["allow_list", "deny_list"], var.model_permission_mode)134 error_message = "The model permission mode must be allow_list or deny_list."135 }136}137138variable "model_ids" {139 type = list(string)140 description = "Model IDs included in the project model policy."141}142143variable "hosted_tools" {144 type = object({145 file_search = bool146 web_search = bool147 image_generation = bool148 mcp = bool149 code_interpreter = bool150 })151 description = "Hosted tools enabled for the project."152}153154variable "project_data_retention_type" {155 type = string156 description = "Approved data-retention type for the project."157158 validation {159 condition = contains([160 "organization_default",161 "none",162 "zero_data_retention",163 "modified_abuse_monitoring",164 "enhanced_zero_data_retention",165 "enhanced_modified_abuse_monitoring",166 ], var.project_data_retention_type)167 error_message = "Provide a supported project data-retention type."168 }169}170171resource "openai_project_model_permissions" "application" {172 project_id = var.project_id173 mode = var.model_permission_mode174 model_ids = var.model_ids175}176177resource "openai_project_hosted_tool_permissions" "application" {178 project_id = var.project_id179 file_search_enabled = var.hosted_tools.file_search180 web_search_enabled = var.hosted_tools.web_search181 image_generation_enabled = var.hosted_tools.image_generation182 mcp_enabled = var.hosted_tools.mcp183 code_interpreter_enabled = var.hosted_tools.code_interpreter184}185186resource "openai_project_data_retention" "application" {187 project_id = var.project_id188 type = var.project_data_retention_type189}190191output "controlled_project_id" {192 value = var.project_id193}194195output "model_permission_mode" {196 value = openai_project_model_permissions.application.mode197}198199output "project_data_retention_type" {200 value = openai_project_data_retention.application.type201}202```203204Create `terraform.tfvars` with an existing project ID, visible model IDs, the hosted-tool policy, and an approved retention type:205206```terraform207project_id = "proj_123"208model_permission_mode = "allow_list"209model_ids = ["gpt-5.4-mini"]210211hosted_tools = {212 file_search = true213 web_search = true214 image_generation = true215 mcp = true216 code_interpreter = true217}218219project_data_retention_type = "organization_default"220```221222The example enables all hosted tools so it can run when the organization policy enables tools for every project. Change a value to `false` only after the corresponding organization-level policy uses selected-project access. Confirm that the model ID and retention type are available to your organization before applying.223224Initialize Terraform, then review and apply a saved plan:225226```bash227terraform init228terraform fmt229terraform validate230terraform plan -out=tfplan231terraform show tfplan232terraform apply tfplan233```234235The first plan should contain three resources to add. For hosted-tool and data-retention controls, an addition means Terraform starts managing an existing singleton project setting; it doesn't create a separate remote object. Model permissions create or update the project's model-permission configuration.236237Run `terraform plan` again to confirm that the configuration produces no further changes. If it shows drift, determine whether another administrator or automation changed a project control before applying another update.