Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: OpenAI Roles API
description: The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.
version: 2.3.0
termsOfService: https://openai.com/policies/terms-of-use
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Roles
paths:
/organization/roles:
get:
security:
- AdminApiKeyAuth: []
summary: Lists the roles configured for the organization.
operationId: list-roles
tags:
- Roles
parameters:
- name: limit
in: query
description: A limit on the number of roles to return. Defaults to 1000.
required: false
schema:
type: integer
minimum: 0
maximum: 1000
default: 1000
- name: after
in: query
description: Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles.
required: false
schema:
type: string
- name: order
in: query
description: Sort order for the returned roles.
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
responses:
'200':
description: Roles listed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicRoleListResource'
x-oaiMeta:
name: List organization roles
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/organization/roles?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const role of client.admin.organization.roles.list()) {\n console.log(role.id);\n}"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\npage = client.admin.organization.roles.list()\npage = page.data[0]\nprint(page.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\tpage, err := client.Admin.Organization.Roles.List(context.TODO(), openai.AdminOrganizationRoleListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.roles.RoleListPage;\nimport com.openai.models.admin.organization.roles.RoleListParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n RoleListPage page = client.admin().organization().roles().list();\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
page = openai.admin.organization.roles.list
puts(page)'
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n"
post:
security:
- AdminApiKeyAuth: []
summary: Creates a custom role for the organization.
operationId: create-role
tags:
- Roles
requestBody:
description: Parameters for the role you want to create.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCreateOrganizationRoleBody'
responses:
'200':
description: Role created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
x-oaiMeta:
name: Create organization role
group: administration
examples:
request:
curl: "curl -X POST https://api.openai.com/v1/organization/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n }'\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst role = await client.admin.organization.roles.create({\n permissions: ['string'],\n role_name: 'role_name',\n});\n\nconsole.log(role.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nrole = client.admin.organization.roles.create(\n permissions=[\"string\"],\n role_name=\"role_name\",\n)\nprint(role.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\trole, err := client.Admin.Organization.Roles.New(context.TODO(), openai.AdminOrganizationRoleNewParams{\n\t\tPermissions: []string{\"string\"},\n\t\tRoleName: \"role_name\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", role.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.roles.Role;\nimport com.openai.models.admin.organization.roles.RoleCreateParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n RoleCreateParams params = RoleCreateParams.builder()\n .addPermission(\"string\")\n .roleName(\"role_name\")\n .build();\n Role role = client.admin().organization().roles().create(params);\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
role = openai.admin.organization.roles.create(permissions: ["string"], role_name: "role_name")
puts(role)'
response: "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n"
/organization/roles/{role_id}:
post:
security:
- AdminApiKeyAuth: []
summary: Updates an existing organization role.
operationId: update-role
tags:
- Roles
parameters:
- name: role_id
in: path
description: The ID of the role to update.
required: true
schema:
type: string
requestBody:
description: Fields to update on the role.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUpdateOrganizationRoleBody'
responses:
'200':
description: Role updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
x-oaiMeta:
name: Update organization role
group: administration
examples:
request:
curl: "curl -X POST https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n }'\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst role = await client.admin.organization.roles.update('role_id');\n\nconsole.log(role.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nrole = client.admin.organization.roles.update(\n role_id=\"role_id\",\n)\nprint(role.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\trole, err := client.Admin.Organization.Roles.Update(\n\t\tcontext.TODO(),\n\t\t\"role_id\",\n\t\topenai.AdminOrganizationRoleUpdateParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", role.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.roles.Role;\nimport com.openai.models.admin.organization.roles.RoleUpdateParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n Role role = client.admin().organization().roles().update(\"role_id\");\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
role = openai.admin.organization.roles.update("role_id")
puts(role)'
response: "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n"
delete:
security:
- AdminApiKeyAuth: []
summary: Deletes a custom role from the organization.
operationId: delete-role
tags:
- Roles
parameters:
- name: role_id
in: path
description: The ID of the role to delete.
required: true
schema:
type: string
responses:
'200':
description: Role deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RoleDeletedResource'
x-oaiMeta:
name: Delete organization role
group: administration
examples:
request:
curl: "curl -X DELETE https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst role = await client.admin.organization.roles.delete('role_id');\n\nconsole.log(role.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nrole = client.admin.organization.roles.delete(\n \"role_id\",\n)\nprint(role.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\trole, err := client.Admin.Organization.Roles.Delete(context.TODO(), \"role_id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", role.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.roles.RoleDeleteParams;\nimport com.openai.models.admin.organization.roles.RoleDeleteResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n RoleDeleteResponse role = client.admin().organization().roles().delete(\"role_id\");\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
role = openai.admin.organization.roles.delete("role_id")
puts(role)'
response: "{\n \"object\": \"role.deleted\",\n \"id\": \"role_01J1F8ROLE01\",\n \"deleted\": true\n}\n"
/projects/{project_id}/roles:
get:
security:
- AdminApiKeyAuth: []
summary: Lists the roles configured for a project.
operationId: list-project-roles
tags:
- Roles
parameters:
- name: project_id
in: path
description: The ID of the project to inspect.
required: true
schema:
type: string
- name: limit
in: query
description: A limit on the number of roles to return. Defaults to 1000.
required: false
schema:
type: integer
minimum: 0
maximum: 1000
default: 1000
- name: after
in: query
description: Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles.
required: false
schema:
type: string
- name: order
in: query
description: Sort order for the returned roles.
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
responses:
'200':
description: Project roles listed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicRoleListResource'
x-oaiMeta:
name: List project roles
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const role of client.admin.organization.projects.roles.list('project_id')) {\n console.log(role.id);\n}"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\npage = client.admin.organization.projects.roles.list(\n project_id=\"project_id\",\n)\npage = page.data[0]\nprint(page.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\tpage, err := client.Admin.Organization.Projects.Roles.List(\n\t\tcontext.TODO(),\n\t\t\"project_id\",\n\t\topenai.AdminOrganizationProjectRoleListParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.projects.roles.RoleListPage;\nimport com.openai.models.admin.organization.projects.roles.RoleListParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n RoleListPage page = client.admin().organization().projects().roles().list(\"project_id\");\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
page = openai.admin.organization.projects.roles.list("project_id")
puts(page)'
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n"
post:
security:
- AdminApiKeyAuth: []
summary: Creates a custom role for a project.
operationId: create-project-role
tags:
- Roles
parameters:
- name: project_id
in: path
description: The ID of the project to update.
required: true
schema:
type: string
requestBody:
description: Parameters for the project role you want to create.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCreateOrganizationRoleBody'
responses:
'200':
description: Project role created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
x-oaiMeta:
name: Create project role
group: administration
examples:
request:
curl: "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"description\": \"Allows managing API keys for the project\"\n }'\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst role = await client.admin.organization.projects.roles.create('project_id', {\n permissions: ['string'],\n role_name: 'role_name',\n});\n\nconsole.log(role.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nrole = client.admin.organization.projects.roles.create(\n project_id=\"project_id\",\n permissions=[\"string\"],\n role_name=\"role_name\",\n)\nprint(role.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\trole, err := client.Admin.Organization.Projects.Roles.New(\n\t\tcontext.TODO(),\n\t\t\"project_id\",\n\t\topenai.AdminOrganizationProjectRoleNewParams{\n\t\t\tPermissions: []string{\"string\"},\n\t\t\tRoleName: \"role_name\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", role.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.projects.roles.RoleCreateParams;\nimport com.openai.models.admin.organization.roles.Role;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n RoleCreateParams params = RoleCreateParams.builder()\n .projectId(\"project_id\")\n .addPermission(\"string\")\n .roleName(\"role_name\")\n .build();\n Role role = client.admin().organization().projects().roles().create(params);\n }\n}"
ruby: "require \"openai\"\n\nopenai = OpenAI::Client.new(admin_api_key: \"My Admin API Key\")\n\nrole = openai.admin.organization.projects.roles.create(\n \"project_id\",\n permissions: [\"string\"],\n role_name: \"role_name\"\n)\n\nputs(role)"
response: "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n"
/projects/{project_id}/roles/{role_id}:
post:
security:
- AdminApiKeyAuth: []
summary: Updates an existing project role.
operationId: update-project-role
tags:
- Roles
parameters:
- name: project_id
in: path
description: The ID of the project to update.
required: true
schema:
type: string
- name: role_id
in: path
description: The ID of the role to update.
required: true
schema:
type: string
requestBody:
description: Fields to update on the project role.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUpdateOrganizationRoleBody'
responses:
'200':
description: Project role updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
x-oaiMeta:
name: Update project role
group: administration
examples:
request:
curl: "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"description\": \"Allows managing API keys for the project\"\n }'\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst role = await client.admin.organization.projects.roles.update('role_id', {\n project_id: 'project_id',\n});\n\nconsole.log(role.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nrole = client.admin.organization.projects.roles.update(\n role_id=\"role_id\",\n project_id=\"project_id\",\n)\nprint(role.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\trole, err := client.Admin.Organization.Projects.Roles.Update(\n\t\tcontext.TODO(),\n\t\t\"project_id\",\n\t\t\"role_id\",\n\t\topenai.AdminOrganizationProjectRoleUpdateParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", role.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.projects.roles.RoleUpdateParams;\nimport com.openai.models.admin.organization.roles.Role;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n RoleUpdateParams params = RoleUpdateParams.builder()\n .projectId(\"project_id\")\n .roleId(\"role_id\")\n .build();\n Role role = client.admin().organization().projects().roles().update(params);\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
role = openai.admin.organization.projects.roles.update("role_id", project_id: "project_id")
puts(role)'
response: "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n"
delete:
security:
- AdminApiKeyAuth: []
summary: Deletes a custom role from a project.
operationId: delete-project-role
tags:
- Roles
parameters:
- name: project_id
in: path
description: The ID of the project to update.
required: true
schema:
type: string
- name: role_id
in: path
description: The ID of the role to delete.
required: true
schema:
type: string
responses:
'200':
description: Project role deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RoleDeletedResource'
x-oaiMeta:
name: Delete project role
group: administration
examples:
request:
curl: "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst role = await client.admin.organization.projects.roles.delete('role_id', {\n project_id: 'project_id',\n});\n\nconsole.log(role.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nrole = client.admin.organization.projects.roles.delete(\n role_id=\"role_id\",\n project_id=\"project_id\",\n)\nprint(role.id)"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\trole, err := client.Admin.Organization.Projects.Roles.Delete(\n\t\tcontext.TODO(),\n\t\t\"project_id\",\n\t\t\"role_id\",\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", role.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.projects.roles.RoleDeleteParams;\nimport com.openai.models.admin.organization.projects.roles.RoleDeleteResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n RoleDeleteParams params = RoleDeleteParams.builder()\n .projectId(\"project_id\")\n .roleId(\"role_id\")\n .build();\n RoleDeleteResponse role = client.admin().organization().projects().roles().delete(params);\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
role = openai.admin.organization.projects.roles.delete("role_id", project_id: "project_id")
puts(role)'
response: "{\n \"object\": \"role.deleted\",\n \"id\": \"role_01J1F8PROJ\",\n \"deleted\": true\n}\n"
components:
schemas:
PublicCreateOrganizationRoleBody:
type: object
description: Request payload for creating a custom role.
properties:
role_name:
type: string
description: Unique name for the role.
permissions:
type: array
description: Permissions to grant to the role.
items:
type: string
description:
description: Optional description of the role.
anyOf:
- type: string
- type: 'null'
required:
- role_name
- permissions
x-oaiMeta:
example: "{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n}\n"
PublicUpdateOrganizationRoleBody:
type: object
description: Request payload for updating an existing role.
properties:
permissions:
description: Updated set of permissions for the role.
anyOf:
- type: array
items:
type: string
- type: 'null'
description:
description: New description for the role.
anyOf:
- type: string
- type: 'null'
role_name:
description: New name for the role.
anyOf:
- type: string
- type: 'null'
x-oaiMeta:
example: "{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n}\n"
Role:
type: object
description: Details about a role that can be assigned through the public Roles API.
properties:
object:
type: string
enum:
- role
description: Always `role`.
x-stainless-const: true
id:
type: string
description: Identifier for the role.
name:
type: string
description: Unique name for the role.
description:
description: Optional description of the role.
anyOf:
- type: string
- type: 'null'
permissions:
type: array
description: Permissions granted by the role.
items:
type: string
resource_type:
type: string
description: Resource type the role is bound to (for example `api.organization` or `api.project`).
predefined_role:
type: boolean
description: Whether the role is predefined and managed by OpenAI.
required:
- object
- id
- name
- description
- permissions
- resource_type
- predefined_role
x-oaiMeta:
name: The role object
example: "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8RO
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-roles-api-openapi.yml