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

List user organization role assignments

GET
/organization/users/{user_id}/roles

Lists the organization roles assigned to a user within the organization.

List user organization role assignments

curl https://api.openai.com/v1/organization/users/user_abc123/roles \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"
Response example
{
    "object": "list",
    "data": [
        {
            "id": "role_01J1F8ROLE01",
            "name": "API Group Manager",
            "permissions": [
                "api.groups.read",
                "api.groups.write"
            ],
            "resource_type": "api.organization",
            "predefined_role": false,
            "description": "Allows managing organization groups",
            "created_at": 1711471533,
            "updated_at": 1711472599,
            "created_by": "user_abc123",
            "created_by_user_obj": {
                "id": "user_abc123",
                "name": "Ada Lovelace",
                "email": "ada@example.com"
            },
            "metadata": {},
            "assignment_sources": [
                {
                    "principal_id": "user_abc123",
                    "principal_type": "user"
                }
            ]
        }
    ],
    "has_more": false,
    "next": null
}
Path Parameters
user_id: string

The ID of the user to inspect.

Query Parameters
after: optional string

Cursor for pagination. Provide the value from the previous response’s next field to continue listing organization roles.

limit: optional integer

A limit on the number of organization role assignments to return.

minimum0
maximum1000
order: optional "asc" or "desc"

Sort order for the returned organization roles.

One of the following:
"asc"
"desc"
Returns
data: array of object { id, assignment_sources, created_at, 9 more }

Role assignments returned in the current page.

id: string

Identifier for the role.

assignment_sources: array of object { principal_id, principal_type } or null

Principals from which the role assignment is inherited, when available.

principal_id: string
principal_type: string
created_at: integer or null

When the role was created.

formatunixtime
created_by: string or null

Identifier of the actor who created the role.

created_by_user_obj: map[unknown] or null

User details for the actor that created the role, when available.

description: string or null

Description of the role.

metadata: map[unknown] or null

Arbitrary metadata stored on the role.

name: string

Name of the role.

permissions: array of string

Permissions associated with the role.

predefined_role: boolean

Whether the role is predefined by OpenAI.

resource_type: string

Resource type the role applies to.

updated_at: integer or null

When the role was last updated.

formatunixtime
has_more: boolean

Whether additional assignments are available when paginating.

object: "list"

Always list.

Returns Examples
Response example
{
    "object": "list",
    "data": [
        {
            "id": "role_01J1F8ROLE01",
            "name": "API Group Manager",
            "permissions": [
                "api.groups.read",
                "api.groups.write"
            ],
            "resource_type": "api.organization",
            "predefined_role": false,
            "description": "Allows managing organization groups",
            "created_at": 1711471533,
            "updated_at": 1711472599,
            "created_by": "user_abc123",
            "created_by_user_obj": {
                "id": "user_abc123",
                "name": "Ada Lovelace",
                "email": "ada@example.com"
            },
            "metadata": {},
            "assignment_sources": [
                {
                    "principal_id": "user_abc123",
                    "principal_type": "user"
                }
            ]
        }
    ],
    "has_more": false,
    "next": null
}