OpenAI Terraform Provider Tutorial: Projects as Code

OpenAI released its official Terraform provider on July 29, 2026, with a stable v1.0.0 build. That sounds like plumbing because it is—and plumbing gets interesting when the alternative is an administrator clicking through production settings with no diff, no reviewer, and no reliable account of what changed.

The useful part of an OpenAI Terraform provider tutorial is not another hello-world project. It is the review chain: create the boundary, grant least privilege through a group, apply a saved plan, and require a clean second plan. That puts OpenAI administration where infrastructure decisions belong: in code review.

What the official provider actually changes

The July 29 provider announcement covers OpenAI API Platform resources including projects, users, groups, roles, access assignments, service accounts, certificates, and project-level rate limits. The provider talks to the Administration API, so it manages the control plane around an application—not the model requests inside it.

The practical difference is reviewability. A proposed permission change appears in terraform plan; a teammate can inspect it before apply; a later plan can expose configuration drift. Terraform does not make a permissive role safe, naturally. It merely gives someone a clean opportunity to say, “Why does the webhook reader need the keys to the kingdom?”

The configuration also answers three governance questions: who owns the group, which actions the role permits, and where the assignment applies. Terraform state is not an audit log. It does, however, stop the desired setup from living only in an administrator’s memory—a storage format with impressive latency and terrible redundancy.

OpenAI Terraform provider tutorial prerequisites

You need Terraform 1.0 or later and permission to create an OpenAI Admin API key. Import blocks, used when adopting existing resources, require Terraform 1.5 or later. The official provider setup guide makes one credential distinction easy to miss: an Admin API key works with administration endpoints, not ordinary model endpoints.

Export that key as an environment variable or inject it through your secrets manager. Do not put it in HCL, terraform.tfvars, or source control.

export OPENAI_ADMIN_KEY="<your-admin-api-key>"

Create main.tf with the provider constraint:

terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = ">= 1.0.0"
    }
  }
}

provider "openai" {}

Then initialize, format, and validate the directory:

terraform init
terraform fmt
terraform validate

terraform init creates .terraform.lock.hcl. Commit that file so another machine resolves the same provider build. Deliberate version changes are the Terraform version of dependency controls before production: boring right up until they save the afternoon.

The provider can also read OPENAI_ORG_ID and OPENAI_PROJECT_ID when you want requests to identify a particular organization or project explicitly. They are optional when OpenAI can resolve scope from the admin key. In CI, keep the admin key in the runner’s secret store, expose it only to the plan or apply job, and mask it from logs. “But it was only in the pipeline output” is not a security control.

Build the five-resource access graph

OpenAI’s projects-and-access workflow uses five resources. The apparent verbosity is useful because it exposes every edge in the permission graph.

Define the project and role

variable "project_name" {
  type = string
}

variable "project_role_permissions" {
  type = list(string)
}

variable "user_id" {
  type = string
}

resource "openai_project" "application" {
  name = var.project_name
}

resource "openai_project_role" "application" {
  project_id  = openai_project.application.project_id
  role_name   = "Application API access"
  description = "Permissions approved for this application"
  permissions = var.project_role_permissions
}

The project is the boundary for usage, service accounts, limits, alerts, and settings. The role says what an identity may do inside that boundary. OpenAI’s example uses api.webhooks.read; substitute only the permission identifiers approved for your workload. This is the same authority-first logic behind a least-privilege agent checklist: capability without a boundary is just an incident with a calendar invite.

Connect the group and user

resource "openai_group" "application_access" {
  name = "${var.project_name}-access"
}

resource "openai_project_group_role" "application_access" {
  project_id = openai_project.application.project_id
  group_id   = openai_group.application_access.group_id
  role_id    = openai_project_role.application.role_id
}

resource "openai_group_user" "application_developer" {
  group_id = openai_group.application_access.group_id
  user_id  = var.user_id
}

Resource	Job	If omitted
openai_project	Creates the application boundary	Nothing has a project scope
openai_project_role	Defines allowed actions	No custom least-privilege role
openai_group	Collects identities	Assignments become one-off
openai_project_group_role	Connects group, role, and project	The group receives no access
openai_group_user	Adds the existing user	The user inherits nothing

The assignment resource does the granting. A role sitting beside a group is not access, any more than a badge sitting beside a locked door is entry.

If an identity platform already owns the group, replace the managed openai_group resource with an openai_group data source and its known group ID. That lets Terraform read the object without claiming its lifecycle. Keep SCIM-managed membership in the identity system that owns it; two control planes editing the same guest list is how access reviews become archaeology.

Put environment-specific values in terraform.tfvars:

project_name = "example-application-development"
user_id      = "user_123"

project_role_permissions = [
  "api.webhooks.read",
]

Plan, apply, and prove there is no drift

Save the plan, inspect it, and apply that exact artifact:

terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan
terraform plan

The first plan should add five resources. The final plan should report no changes. That second result matters more than the celebratory “Apply complete” because it proves the declared configuration and remote state agree.

Review the plan as a permission graph, not as a resource counter. Confirm the project name, inspect every permission added to the custom role, verify the group ID, and match the user ID to an existing organization identity. Five green plus signs can still describe a beautifully reproducible mistake.

For CI, the import and reconciliation guide recommends terraform plan -detailed-exitcode: exit code 0 means no changes, 2 means the plan contains changes, and 1 means Terraform hit an error. That is a usable drift signal, not a blob of terminal prose begging to be ignored.

A managed project can hold something like an OpenAI Agents SDK workflow, but automation scales the permission model you give it—good or bad. Require a reviewer who understands the role diff.

Add guardrails without confusing alerts for limits

The provider can manage project rate limits and monthly spend alerts. They solve different problems.

• Spend alert: emails recipients after tracked monthly spend crosses a threshold. The amount is in cents, so 20000 means USD 200.
• Project rate limit: updates an existing model-specific record for request or token volume. Its rate_limit_id is a record ID, not a model name.

The rate-limit and spend guide is blunt: a spend alert does not stop requests or enforce a cap. It is a smoke alarm, not a circuit breaker. Rate limits constrain traffic, not a monthly dollar ceiling.

resource "openai_project_spend_alert" "monthly" {
  project_id                      = openai_project.application.project_id
  threshold_amount                = 20000
  currency                        = "USD"
  interval                        = "month"
  notification_channel_type       = "email"
  notification_channel_recipients = ["platform-alerts@example.com"]
}

Treat that email as the start of an operational response: name the recipient, escalation path, and action before the alert fires. Then configure model-specific request and token limits separately. A warning delivered to an unattended mailbox is merely a receipt with ambitions.

Lifecycle behavior deserves the same caution. Destroying an openai_project archives it, and OpenAI says an archived project cannot be restored. Removing some rate-limit resources from configuration can remove them from Terraform state without resetting the remote setting.

For existing production resources, declare the current remote settings first, add the correct import block, and preview the import in a saved plan. If that plan proposes a remote update, stop and make the configuration match reality. Apply the import only when the plan shows adoption without mutation, then run another plan and require no changes before introducing an intentional edit.

The pull request is not the policy

Will teams make OpenAI access changes earn the same review as databases and IAM—or simply automate permissive dashboard habits faster?

Infrastructure as code does not create governance. It creates a place where governance can finally happen, with a diff that names the project, the identity, and every permission someone is about to grant.

The next official provider release after v1.0.0 is the catalyst to watch. Its changelog will show whether OpenAI is extending Terraform from reviewable access and alerting into enforceable cost controls—or leaving that circuit breaker on the other side of the API.