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 project roles

GET
/projects/{project_id}/roles

Lists the roles configured for a project.

List project roles

curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"
Response example
{
    "object": "list",
    "data": [
        {
            "object": "role",
            "id": "role_01J1F8PROJ",
            "name": "API Project Key Manager",
            "description": "Allows managing API keys for the project",
            "permissions": [
                "api.organization.projects.api_keys.read",
                "api.organization.projects.api_keys.write"
            ],
            "resource_type": "api.project",
            "predefined_role": false
        }
    ],
    "has_more": false,
    "next": null
}
Path Parameters
project_id: string

The ID of the project to inspect.

Query Parameters
after: optional string

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

limit: optional integer (default: 1000)

A limit on the number of roles to return. Defaults to 1000.

minimum0
maximum1000
order: optional "asc" or "desc" (default: "asc")

Sort order for the returned roles.

One of the following:
"asc"
"desc"
Returns
data: array of Role { id, description, name, 4 more }

Roles returned in the current page.

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

has_more: boolean

Whether more roles are available when paginating.

object: "list"

Always list.

Returns Examples
Response example
{
    "object": "list",
    "data": [
        {
            "object": "role",
            "id": "role_01J1F8PROJ",
            "name": "API Project Key Manager",
            "description": "Allows managing API keys for the project",
            "permissions": [
                "api.organization.projects.api_keys.read",
                "api.organization.projects.api_keys.write"
            ],
            "resource_type": "api.project",
            "predefined_role": false
        }
    ],
    "has_more": false,
    "next": null
}