API Reference

Admin

Organization

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Groups

Create group

POST/organization/groups

Delete group

DELETE/organization/groups/{group_id}

List groups

GET/organization/groups

Retrieve group

GET/organization/groups/{group_id}

Update group

POST/organization/groups/{group_id}

ModelsExpand Collapse

Group object { id, created_at, group_type, 2 more }

Details about an organization group.

id: string

Identifier for the group.

created_at: number

Unix timestamp (in seconds) when the group was created.

formatunixtime

group_type: "group" or "tenant_group"

The type of the group.

One of the following:

"group"

"tenant_group"

is_scim_managed: boolean

Whether the group is managed through SCIM and controlled by your identity provider.

name: string

Display name of the group.

GroupDeleteResponse object { id, deleted, object }

Confirmation payload returned after deleting a group.

id: string

Identifier of the deleted group.

deleted: boolean

Whether the group was deleted.

object: "group.deleted"

Always group.deleted.

GroupUpdateResponse object { id, created_at, is_scim_managed, name }

Response returned after updating a group.

id: string

Identifier for the group.

created_at: number

Unix timestamp (in seconds) when the group was created.

formatunixtime

is_scim_managed: boolean

Whether the group is managed through SCIM and controlled by your identity provider.

name: string

Updated display name for the group.

GroupsRoles

Assign organization role to group

POST/organization/groups/{group_id}/roles

Unassign organization role from group

DELETE/organization/groups/{group_id}/roles/{role_id}

List group organization role assignments

GET/organization/groups/{group_id}/roles

Retrieve group organization role

GET/organization/groups/{group_id}/roles/{role_id}

ModelsExpand Collapse

RoleCreateResponse object { group, object, role }

Role assignment linking a group to a role.

group: object { id, created_at, name, 2 more }

Summary information about a group returned in role assignment responses.

id: string

Identifier for the group.

created_at: number

Unix timestamp (in seconds) when the group was created.

formatunixtime

name: string

Display name of the group.

object: "group"

Always group.

scim_managed: boolean

Whether the group is managed through SCIM.

object: "group.role"

Always group.role.

role: Role { id, description, name, 4 more }

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

RoleDeleteResponse object { deleted, object }

Confirmation payload returned after unassigning a role.

deleted: boolean

Whether the assignment was removed.

object: string

Identifier for the deleted assignment, such as group.role.deleted or user.role.deleted.

RoleListResponse object { id, assignment_sources, created_at, 9 more }

Detailed information about a role assignment entry returned when listing assignments.

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: number 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: number or null

When the role was last updated.

formatunixtime

RoleRetrieveResponse object { id, assignment_sources, created_at, 9 more }

Detailed information about a role assignment entry returned when listing assignments.

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: number 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: number or null

When the role was last updated.

formatunixtime

GroupsUsers

Add group user

POST/organization/groups/{group_id}/users

Remove group user

DELETE/organization/groups/{group_id}/users/{user_id}

List group users

GET/organization/groups/{group_id}/users

Retrieve group user

GET/organization/groups/{group_id}/users/{user_id}

ModelsExpand Collapse

OrganizationGroupUser object { id, email, name }

Represents an individual user returned when inspecting group membership.

id: string

The identifier, which can be referenced in API endpoints

email: string or null

The email address of the user.

name: string

The name of the user.

UserCreateResponse object { group_id, object, user_id }

Confirmation payload returned after adding a user to a group.

group_id: string

Identifier of the group the user was added to.

object: "group.user"

Always group.user.

user_id: string

Identifier of the user that was added.

UserDeleteResponse object { deleted, object }

Confirmation payload returned after removing a user from a group.

deleted: boolean

Whether the group membership was removed.

object: "group.user.deleted"

Always group.user.deleted.

UserRetrieveResponse object { id, email, is_service_account, 3 more }

Details about a user returned from an organization group membership lookup.

id: string

Identifier for the user.

email: string or null

Email address of the user, or null for users without an email.

is_service_account: boolean or null

Whether the user is a service account.

name: string

Display name of the user.

picture: string or null

URL of the user’s profile picture, if available.

user_type: "user" or "tenant_user"

The type of user.

One of the following:

"user"

"tenant_user"