API Reference

Organization

Roles

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create organization role

POST/organization/roles

Creates a custom role for the organization.

Body ParametersJSONExpand Collapse

permissions: array of string

Permissions to grant to the role.

role_name: string

Unique name for the role.

description: optional string

Optional description of the role.

ReturnsExpand Collapse

id: string

Identifier for the role.

description: string

Optional description of the role.

name: string

Unique name for the role.

object: "role"

Always role.

permissions: array of string

Permissions granted by the role.

predefined_role: boolean

Whether the role is predefined and managed by OpenAI.

resource_type: string

Resource type the role is bound to (for example api.organization or api.project).

Create organization role

HTTP

HTTP

TypeScript

Python

Java

Go

Ruby

curl -X POST https://api.openai.com/v1/organization/roles \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "role_name": "API Group Manager",
      "permissions": [
          "api.groups.read",
          "api.groups.write"
      ],
      "description": "Allows managing organization groups"
  }'

{
    "object": "role",
    "id": "role_01J1F8ROLE01",
    "name": "API Group Manager",
    "description": "Allows managing organization groups",
    "permissions": [
        "api.groups.read",
        "api.groups.write"
    ],
    "resource_type": "api.organization",
    "predefined_role": false
}

Returns Examples

{
    "object": "role",
    "id": "role_01J1F8ROLE01",
    "name": "API Group Manager",
    "description": "Allows managing organization groups",
    "permissions": [
        "api.groups.read",
        "api.groups.write"
    ],
    "resource_type": "api.organization",
    "predefined_role": false
}