OpenAI Terraform Provider 1.0 tutorial: Managing API Platform with IaC

On July 29, 2026, OpenAI released the official Terraform Provider 1.0, allowing API Platform management objects to enter the Infrastructure as Code workflow. Teams no longer need to rely solely on the console to manually create projects, add members, or adjust rate limits; instead, they can write target states into Terraform configurations and manage changes through code review, execution plans, and status file management. The official Provider address is: openai/terraform-provider-openai.

What can this Provider manage?

OpenAI Terraform Provider calls the Administration API, mainly targeting control plane resources for organizations and projects. Common objects currently covered by the documentation include:

• Organize projects and project members.
• Organize users, invitations, user groups, and roles.
• Project-level assignment of users, user groups, and roles.
• Project service account.
• Associate the organizational certificate with the project certificate.
• Project model permissions and Hosted Tool permissions.
• Project data retention strategies.
• Organization and project expenditure reminders.
• Project-level rate limits.

Provider also provides a large number of Data Sources, allowing queries of existing projects, users, roles, certificates, and restrictions, avoiding hard-encoding all IDs in configuration. It is suitable for the following scenarios:

• Establish a consistent OpenAI project structure for development, testing, and production environments.
• Review permissions and quota changes through Pull Requests.
• Gradually import existing console resources into Terraform.
• Run regularly terraform plan manually modify the detection console.
• Reuse project, role, and restriction templates for different teams.

Two key migration points in 1.0.0

1.0.0 was the first official version, but upgrading from the early preview version could not only change the version number. This version removed the deprecated rate-limiting resources of the aggregation project. Projects should now use single-entry openai_project_rate_limit resources, each corresponding to an existing rate_limit_id. Additionally, Provider request resilience and telemetry have been improved, but this does not change Terraform’s state management principles: production environments should still perform plan first, confirm the scope of changes, and then apply.

Prerequisites

Before you start, you need:

• Terraform CLI 1.0 or later.
• OpenAI API Platform Organizational Authority.
• An OpenAI Admin API Key.
• A secure backend for preserving Terraform state.

The Admin API Key serves a different purpose than a regular project API Key. It is used for the Administration API and cannot be used to call the standard model inference interface. After creating the Admin API Key in the organizational settings of OpenAI API Platform, it is passed in via environment variables:

1

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

PowerShell can be configured like this:

1

$env:OPENAI_ADMIN_KEY = "<your-admin-api-key>"

Do not write management keys into .tf files, variable default values, or Git repositories. CI/CD environments should use Secret Store injection and restrict who can read execution logs and Terraform states.

Initialize the official provider

New versions.tf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

terraform {
  required_version = ">= 1.0"

  required_providers {
    openai = {
      source  = "openai/openai"
      version = "~> 1.0"
    }
  }
}

Recreate provider.tf:

1
2
3
4

provider "openai" {
  # 默认读取 OPENAI_ADMIN_KEY。
  # organization 和 project 也可由环境变量提供。
}

Available Provider parameters include:

• admin_api_key: Admin API Key, which is a sensitive field.
• organization: Organization ID.
• project: Default project ID.
• base_url: The base address for OpenAI API requests.

The corresponding environment variables include OPENAI_ADMIN_KEY, OPENAI_ORG_ID, and OPENAI_PROJECT_ID. Initialize the working directory:

1
2

terraform init
terraform providers

When submitting code, .terraform.lock.hcl should be submitted together to ensure the CI and local use of the confirmed Provider version.

Creating an OpenAI project

The smallest project resource only needs a name:

1
2
3
4
5
6
7

resource "openai_project" "production" {
  name = "production-api"
}

output "production_project_id" {
  value = openai_project.production.project_id
}

geography is an optional field; whether to set it should be based on the actual API Platform configuration and compliance requirements. Do not directly modify the regional settings of existing production projects just for examples. First, format and check the configuration:

1
2
3

terraform fmt -check
terraform validate
terraform plan -out=tfplan

Execute only after confirming that the plan only includes expected resources:

1

terraform apply tfplan

Managing Project Members and Roles

You can add existing organizational users to the project:

1
2
3
4
5
6
7
8
9

variable "operator_user_id" {
  type = string
}

resource "openai_project_user" "operator" {
  project_id = openai_project.production.project_id
  user_id    = var.operator_user_id
  role       = "member"
}

If you need to assign independent project roles, the official team provides three built-in project role IDs:

• role-api-project-member
• role-api-project-owner
• role-api-project-viewer

For example, assign read-only roles:

1
2
3
4
5

resource "openai_project_user_role" "viewer" {
  project_id = openai_project.production.project_id
  user_id    = var.operator_user_id
  role_id    = "role-api-project-viewer"
}

You can also dynamically discover roles openai_project_roles Data Source, reducing dependence on fixed IDs. Custom project roles use openai_project_role, with required fields being project_id, role_name, and permissions:

1
2
3
4
5
6

resource "openai_project_role" "auditor" {
  project_id  = openai_project.production.project_id
  role_name   = "API auditor"
  description = "Read-only access for audit automation"
  permissions = ["api.project.read"]
}

Permission strings must come from the actual available permission set. Before going live, verify with Data Source or official API documentation; do not guess permissions based on names.

Invite users who have not yet joined the organization

Organizational invitations can be declared together with project membership status:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

resource "openai_invite" "developer" {
  email = "[email protected]"
  role  = "reader"

  projects = [
    {
      id   = openai_project.production.project_id
      role = "member"
    }
  ]
}

The invitation should have lifecycle states such as accepted or expired. After the recipient accepts, the terraform plan should be rerun to confirm that the remote status and configuration match expectations.

Service accounts do not automatically create API Keys

Configuring a project service account is very simple:

1
2
3
4

resource "openai_project_service_account" "deploy" {
  project_id = openai_project.production.project_id
  name       = "production-deploy"
}

But this resource only creates the service account itself. It clearly sets create_service_account_only=true, does not automatically assign roles, and does not create API Keys. Roles require separate Terraform resource management, while API Keys must be created and managed outside Terraform via public APIs. Do not assume that directly usable keys appear in module output.

Manage Certificates

Organization certificates can be read from PEM files:

1
2
3
4

resource "openai_certificate" "organization" {
  name        = "production-certificate"
  certificate = file("${path.module}/certificates/production.pem")
}

certificate is a sensitive property, but a sensitive tag does not mean the content will not enter the status file. You need to confirm that the remote State is encrypted and restrict access to the State backend, backups, and CI Artifacts. Before certificate rotation, review the planned replacement behavior to ensure the validity of the new and old certificates overlaps, avoiding connection interruptions caused by a single apply.

Configure Model Access

Project model permissions can be used in the allowlist:

1
2
3
4
5

resource "openai_project_model_permissions" "production" {
  project_id = openai_project.production.project_id
  mode       = "allow_list"
  model_ids  = ["gpt-5.6-sol"]
}

Model identification may change with product updates. Before merging configurations, verify the currently available models and confirm that the application migration has been completed before removing the old model license.

Manage Project-Level Rate Limits

openai_project_rate_limit manages existing rate-limited objects and must provide the project ID along with the specific rate_limit_id:

1
2
3
4
5
6

resource "openai_project_rate_limit" "primary_model" {
  project_id               = openai_project.production.project_id
  rate_limit_id            = "rate_limit_123"
  max_requests_per_1_minute = 500
  max_tokens_per_1_minute   = 200000
}

Manageable fields also include daily request count, maximum batch input tokens per day, images per minute, and audio MB per minute. The actual configurable upper limit depends on the organization and model quotas. Terraform can only manage values accepted by the API and cannot bypass platform quotas by increasing configuration numbers.

Importing Existing Resources into Terraform

For resources already created on console, do not create them repeatedly; first write the configuration matching the remote resource and import the State. Terraform 1.5 and above can use import blocks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import {
  to = openai_project.production
  id = "proj_123"
}

import {
  to = openai_project_service_account.deploy
  id = "proj_123/service_account_123"
}

import {
  to = openai_project_rate_limit.primary_model
  id = "proj_123/rate_limit_123"
}

Different resources have different import ID formats. Common formats include a single resource ID, project_id/resource_id, and a three-segment composite ID containing users and roles. The Import section in the corresponding resource documentation should be used as the standard. After importing, run in sequence:

1
2

terraform plan
terraform state show openai_project.production

If the plan immediately shows a large number of updates, it means the local configuration does not fully reflect the remote status. Adjust the configuration first until the plan meets expectations; do not overwrite production settings directly apply.

Use terraform plan to Detect Configuration Drift

When administrators manually modify members, roles, or restrictions in the console, the Provider’s read operation compares the remote state with Terraform configuration. Detailed exit codes can be used in CI:

1
2

terraform init -input=false
terraform plan -input=false -detailed-exitcode

The meaning of the exit code is:

• 0: Configuration matches remote state with no changes.
• 1: If command execution fails, check for permission, network, or configuration errors.
• 2: Detecting changes or drift requires manual review of plans.

Do not automatically execute production apply after detecting exit code 2. Drift may come from emergency handling, permission revocation, or platform-side changes. First, confirm whether to restore the state of code declarations or to synchronize reasonable manual changes back to configuration.

State, Permissions, and Review Recommendations

The Admin API Key can modify the organizational control plane and should be handled as high-privilege credentials. The following protections are recommended:

• Local development only injects keys short-term through environment variables.
• CI uses a dedicated identity and protected secrets.
• Remote State enables encryption, locking, and version retention.
• Divide plan and apply into different approval stages.
• Production environments restrict the branches and personnel capable of executing apply.
• Regularly rotate Admin API keys and revoke unused keys.
• Maintain audit records for imports, role changes, and resource deletions.

Before deleting items, members, roles, or certificates, check the destroy and replace items in the Terraform plan. You can combine prevent_destroy for critical resources, but it cannot replace change review and recovery plans.

Frequently Asked Questions

Can the Provider Call Model APIs?

No, it cannot. It targets the OpenAI Administration API, and the Admin API Key cannot be used for regular model requests.

Do Service Account Resources Return API Keys?

No, it won’t. It only creates service accounts, and roles and API keys need to be managed separately.

Why can’t we create a new rate limit object?

This resource is used to manage rate limits in existing projects and requires providing actual rate_limit_id. 1.0.0 Removed the old aggregate rate limit resource.

Can manual changes to the console be detected?

You can use terraform plan to detect differences between remote state and configuration. After detecting drift, manual judgment should be made on which side to use, rather than unconditionally overriding automatically.

Do existing projects need to be rebuilt?

No, you don’t need to. Use import blocks or terraform import to add resources to State, then gradually complete the configuration.

Summary

OpenAI Terraform Provider 1.0 incorporates API Platform management into the standard IaC flow, suitable for unified management of projects, members, roles, service accounts, certificates, and project restrictions. The most important thing to note during integration is not a single terraform apply, but three things: correctly using Admin API Keys, importing existing resources first, and using terraform plan as a review entry point for permission and configuration drift. In production, special attention is also paid to service account keys, composite resource import IDs, 1.0.0 rate limit resource changes, and Terraform State access security.

Official Resources

• OpenAI Official Terraform Provider
• Provider Documentation Directory
• 1.0.0 Changelog