Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Retrieve organization role

GET
/organization/roles/{role_id}

Retrieves an organization role.

Retrieve organization role

curl https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"
Response example
{
    "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
}
Path Parameters
role_id: string

The ID of the role to retrieve.

Returns
Role object { id, description, name, 4 more }

Details about a role that can be assigned through the public Roles API.

id: string

Identifier for the role.

description: string or null

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).

Returns Examples
Response example
{
    "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
}