Skip to content
Primary navigation

Suggested
API Dashboard
API Reference
Admin
Organization
Users
Roles

Assign organization role to user

admin.organization.users.roles.create(struser_id, RoleCreateParams**kwargs) -> RoleCreateResponse
POST/organization/users/{user_id}/roles

Assigns an organization role to a user within the organization.

ParametersExpand Collapse
user_id: str
role_id: str

Identifier of the role to assign.

ReturnsExpand Collapse
class RoleCreateResponse: …

Role assignment linking a user to a role.

object: Literal["user.role"]

Always user.role.

role: Role

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

id: str

Identifier for the role.

description: Optional[str]

Optional description of the role.

name: str

Unique name for the role.

object: Literal["role"]

Always role.

permissions: List[str]

Permissions granted by the role.

predefined_role: bool

Whether the role is predefined and managed by OpenAI.

resource_type: str

Resource type the role is bound to (for example api.organization or api.project).

user: OrganizationUser

Represents an individual user within an organization.

id: str

The identifier, which can be referenced in API endpoints

added_at: int

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

formatunixtime
object: Literal["organization.user"]

The object type, which is always organization.user

api_key_last_used_at: Optional[int]

The Unix timestamp (in seconds) of the user’s last API key usage.

formatunixtime
created: Optional[int]

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

formatunixtime
developer_persona: Optional[str]

The developer persona metadata for the user.

email: Optional[str]

The email address of the user

is_default: Optional[bool]

Whether this is the organization’s default user.

is_scale_tier_authorized_purchaser: Optional[bool]

Whether the user is an authorized purchaser for Scale Tier.

is_scim_managed: Optional[bool]

Whether the user is managed through SCIM.

is_service_account: Optional[bool]

Whether the user is a service account.

name: Optional[str]

The name of the user

projects: Optional[Projects]

Projects associated with the user, if included.

data: List[ProjectsData]
id: Optional[str]
name: Optional[str]
role: Optional[str]
object: Literal["list"]
role: Optional[str]

owner or reader

technical_level: Optional[str]

The technical level metadata for the user.

user: Optional[User]

Nested user details.

id: str
object: Literal["user"]
banned: Optional[bool]
banned_at: Optional[int]
formatunixtime
email: Optional[str]
enabled: Optional[bool]
name: Optional[str]
picture: Optional[str]

Assign organization role to user

import os
from openai import OpenAI

client = OpenAI(
    admin_api_key=os.environ.get("OPENAI_ADMIN_KEY"),  # This is the default and can be omitted
)
role = client.admin.organization.users.roles.create(
    user_id="user_id",
    role_id="role_id",
)
print(role.object)
{
    "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
    }
}