Repository Public
1# Manage projects and access 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 create an OpenAI project and establish reusable access controls. You will define what identities can do with a project role, collect identities in an organization group, and connect the group to the project.67After completing the main workflow, you will have a repeatable configuration that:89- Creates an OpenAI project for an application.10- Defines a least-privilege project role.11- Creates an organization group for identities that need access.12- Grants the group access to the project through the role.13- Adds an existing organization user to the group.1415## Before you begin1617Complete 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 the ID of an existing organization user and the permission identifiers approved for the application. Use a test organization when evaluating the workflow.1819Destroying an `openai_project` archives the project instead of permanently deleting it. You can't restore an archived project.2021## Create the project boundary2223Create a project for the application:2425```terraform26resource "openai_project" "application" {27 name = "example-application-development"28}29```3031The project creates the boundary for the application's API usage, service accounts, rate limits, spend alerts, and project settings. Terraform makes the generated ID available as `openai_project.application.project_id`. Project-level resources can reference that value, so Terraform creates the project before them.3233This focused example uses a concrete name. The complete example later replaces it with a variable so you can reuse the configuration across environments.3435## Define project permissions3637Create a project role with the permissions approved for the application:3839```terraform40resource "openai_project_role" "application" {41 project_id = openai_project.application.project_id42 role_name = "Application API access"43 description = "Permissions approved for this application"44 permissions = ["api.webhooks.read"]45}46```4748The `openai_project_role` resource defines what an identity can do inside the project. This example grants permission to read webhook configuration. Replace `api.webhooks.read` with the permission identifiers approved for your application, and start with only the permissions it needs.4950Changing `permissions` updates the role. Run `terraform plan` to review every added or removed permission before applying the change.5152## Create or reuse a group5354Create an organization group when Terraform should own its lifecycle:5556```terraform57resource "openai_group" "application_access" {58 name = "example-application-development-access"59}60```6162Groups exist at the organization level, and you can reuse them across projects. A name ending in `-access` communicates that membership grants access rather than merely describing a team.6364If another system owns an existing group, read it instead:6566```terraform67data "openai_group" "application_access" {68 group_id = "group_123"69}70```7172The data source reads the group without making this configuration responsible for its lifecycle. You can read SCIM-managed groups, but keep membership changes in the identity system that owns them.7374## Grant the group project access7576Connect the group to the custom role inside the project:7778```terraform79resource "openai_project_group_role" "application_access" {80 project_id = openai_project.application.project_id81 group_id = openai_group.application_access.group_id82 role_id = openai_project_role.application.role_id83}84```8586This example uses the Terraform-managed group. If you reused an existing group through the data source, replace the `group_id` expression with `data.openai_group.application_access.group_id`.8788The assignment connects three objects:8990- `project_id` identifies where the group receives access.91- `group_id` identifies which collection of identities receives access.92- `role_id` identifies which permissions the group receives.9394Group members inherit the custom role in this project. Adding a role or a group alone doesn't grant access; the assignment is the link between them.9596## Add users and other identities9798Add an identity to a Terraform-managed organization group with `openai_group_user`:99100```terraform101resource "openai_group_user" "application_developer" {102 group_id = openai_group.application_access.group_id103 user_id = "user_123"104}105```106107The `user_id` can identify an existing organization user or service account. To add a service account, use `openai_project_service_account.application.id` as the `user_id`. See [Service accounts](https://developers.openai.com/api/docs/guides/terraform/service-accounts) for group-based service-account access, authentication, and credential-lifecycle requirements.108109Use direct role assignments when group-based access isn't appropriate:110111```terraform112resource "openai_project_user_role" "application_developer" {113 project_id = openai_project.application.project_id114 user_id = "user_123"115 role_id = openai_project_role.application.role_id116}117```118119For organization-wide permissions, create an organization role and assign it directly or through a group:120121```terraform122variable "organization_role_permissions" {123 type = list(string)124}125126resource "openai_role" "platform_operator" {127 role_name = "Platform operator"128 description = "Organization permissions for the platform team"129 permissions = var.organization_role_permissions130}131132resource "openai_user_role" "platform_operator" {133 user_id = "user_123"134 role_id = openai_role.platform_operator.role_id135}136```137138Set `organization_role_permissions` to the approved organization-level permission identifiers. Keep organization permissions separate from project permissions so each assignment has the narrowest required scope.139140## Inspect current assignments141142Read the organization and project roles assigned to an identity before changing access:143144```terraform145data "openai_user_roles" "current" {146 user_id = "user_123"147}148149data "openai_project_user_roles" "current" {150 project_id = openai_project.application.project_id151 user_id = "user_123"152}153154output "organization_roles" {155 value = data.openai_user_roles.current.roles156}157158output "project_roles" {159 value = data.openai_project_user_roles.current.roles160}161```162163Data sources report current assignments but don't make Terraform responsible for them.164165## Remove assignments166167When Terraform already manages an assignment, removing its resource block makes the next plan propose deleting the remote assignment. Review the plan and verify that another path still grants any required access.168169For a pre-existing assignment, first declare the matching resource and import it using the documented composite ID. Confirm that the first plan is a no-op before removing it from configuration and applying the deletion.170171Terraform can remove only assignments recorded in its state. To remove an172 existing default assignment, first import it into the corresponding Terraform173 resource. Then remove that resource from your configuration and apply the174 resulting destroy plan. If your organization doesn't allow this175 import-and-destroy workflow, remove the assignment through an approved176 dashboard or Administration API process.177178See [Import and reconciliation](https://developers.openai.com/api/docs/guides/terraform/import-and-reconcile) for import formats and a safe adoption sequence.179180## Run the complete example181182The focused examples use concrete values to make each relationship clear. The complete configuration replaces repeated, environment-specific values with variables so you can reuse it without changing the resource definitions.183184Save the following configuration as `main.tf`:185186```terraform187terraform {188 required_version = ">= 1.0"189190 required_providers {191 openai = {192 source = "openai/openai"193 version = ">= 1.0.0"194 }195 }196}197198provider "openai" {}199200variable "project_name" {201 type = string202}203204variable "project_role_permissions" {205 type = list(string)206}207208variable "user_id" {209 type = string210}211212resource "openai_project" "application" {213 name = var.project_name214}215216resource "openai_project_role" "application" {217 project_id = openai_project.application.project_id218 role_name = "Application API access"219 description = "Permissions approved for this application"220 permissions = var.project_role_permissions221}222223resource "openai_group" "application_access" {224 name = "${var.project_name}-access"225}226227resource "openai_project_group_role" "application_access" {228 project_id = openai_project.application.project_id229 group_id = openai_group.application_access.group_id230 role_id = openai_project_role.application.role_id231}232233resource "openai_group_user" "application_developer" {234 group_id = openai_group.application_access.group_id235 user_id = var.user_id236}237238output "project_id" {239 value = openai_project.application.project_id240}241242output "group_id" {243 value = openai_group.application_access.group_id244}245246output "project_role_id" {247 value = openai_project_role.application.role_id248}249```250251Create `terraform.tfvars` with a unique project name, an existing organization user ID, and the approved permissions:252253```terraform254project_name = "example-application-development"255user_id = "user_123"256257project_role_permissions = [258 "api.webhooks.read",259]260```261262Initialize Terraform, then review and apply a saved plan:263264```bash265terraform init266terraform fmt267terraform validate268terraform plan -out=tfplan269terraform show tfplan270terraform apply tfplan271```272273The first plan should contain five resources to add. After the apply, the user inherits the custom project role through the group, and `terraform output` prints the project, group, and project-role IDs. Run `terraform plan` again to confirm that the configuration produces no further changes.274275To add more human users, repeat the group membership pattern with a unique Terraform resource name for each user. To configure a nonhuman identity, see [Service accounts](https://developers.openai.com/api/docs/guides/terraform/service-accounts). Use [Model, tool, and data controls](https://developers.openai.com/api/docs/guides/terraform/project-controls) and [Rate limits and spend](https://developers.openai.com/api/docs/guides/terraform/rate-limits-and-spend) to add project guardrails.