Skip to content
Primary navigation

Suggested
API Dashboard
API Reference
Projects
Roles

List project roles

GET/projects/{project_id}/roles

Lists the roles configured for a project.

Path ParametersExpand Collapse
project_id: string
Query ParametersExpand Collapse
after: optional string

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

limit: optional number

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

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

Sort order for the returned roles.

One of the following:
"asc"
"desc"
ReturnsExpand Collapse
data: array of object { id, description, name, 4 more }

Roles returned in the current page.

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

has_more: boolean

Whether more roles are available when paginating.

object: "list"

Always list.

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"

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