API Reference

Organization

Users

Roles

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Assign organization role to user

POST/organization/users/{user_id}/roles

Assigns an organization role to a user within the organization.

Path ParametersExpand Collapse

user_id: string

Body ParametersJSONExpand Collapse

role_id: string

Identifier of the role to assign.

ReturnsExpand Collapse

object: "user.role"

Always user.role.

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

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

user: User { id, added_at, email, 3 more }

Represents an individual user within an organization.

id: string

The identifier, which can be referenced in API endpoints

added_at: number

The Unix timestamp (in seconds) of when the user was added.

email: string

The email address of the user

name: string

The name of the user

object: "organization.user"

The object type, which is always organization.user

role: "owner" or "reader"

owner or reader

One of the following:

"owner"

"reader"

Assign organization role to user

HTTP

HTTP

TypeScript

Python

Java

Go

Ruby

curl -X POST https://api.openai.com/v1/organization/users/user_abc123/roles \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "role_id": "role_01J1F8ROLE01"
  }'

{
    "object": "user.role",
    "user": {
        "object": "organization.user",
        "id": "user_abc123",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "role": "owner",
        "added_at": 1711470000
    },
    "role": {
        "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": "user.role",
    "user": {
        "object": "organization.user",
        "id": "user_abc123",
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "role": "owner",
        "added_at": 1711470000
    },
    "role": {
        "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
    }
}