Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: OpenAI User organization role assignments API
description: The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.
version: 2.3.0
termsOfService: https://openai.com/policies/terms-of-use
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
identifier: MIT
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: User organization role assignments
paths:
/organization/users/{user_id}/roles:
get:
security:
- AdminApiKeyAuth: []
summary: List user organization role assignments
description: Lists the organization roles assigned to a user within the organization.
operationId: list-user-role-assignments
tags:
- User organization role assignments
parameters:
- name: user_id
in: path
description: The ID of the user to inspect.
required: true
schema:
type: string
- name: limit
in: query
description: A limit on the number of organization role assignments to return.
required: false
schema:
type: integer
minimum: 0
maximum: 1000
- name: after
in: query
description: Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles.
required: false
schema:
type: string
- name: order
in: query
description: Sort order for the returned organization roles.
required: false
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: User organization role assignments listed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RoleListResource'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/organization/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n"
post:
security:
- AdminApiKeyAuth: []
summary: Assign organization role to user
description: Assigns an organization role to a user within the organization.
operationId: assign-user-role
tags:
- User organization role assignments
parameters:
- name: user_id
in: path
description: The ID of the user that should receive the organization role.
required: true
schema:
type: string
requestBody:
description: Identifies the organization role to assign to the user.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAssignOrganizationGroupRoleBody'
responses:
'200':
description: Organization role assigned to the user successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UserRoleAssignment'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl -X POST https://api.openai.com/v1/organization/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8ROLE01\"\n }'\n"
response: "{\n \"object\": \"user.role\",\n \"user\": {\n \"object\": \"organization.user\",\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711470000\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n}\n"
/organization/users/{user_id}/roles/{role_id}:
get:
security:
- AdminApiKeyAuth: []
summary: Retrieve user organization role
description: Retrieves an organization role assigned to a user.
operationId: retrieve-user-role
tags:
- User organization role assignments
parameters:
- name: user_id
in: path
description: The ID of the user to inspect.
required: true
schema:
type: string
- name: role_id
in: path
description: The ID of the organization role to retrieve for the user.
required: true
schema:
type: string
responses:
'200':
description: Organization role retrieved for the user successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AssignedRoleDetails'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
response: "{\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n"
delete:
security:
- AdminApiKeyAuth: []
summary: Unassign organization role from user
description: Unassigns an organization role from a user within the organization.
operationId: unassign-user-role
tags:
- User organization role assignments
parameters:
- name: user_id
in: path
description: The ID of the user to modify.
required: true
schema:
type: string
- name: role_id
in: path
description: The ID of the organization role to remove from the user.
required: true
schema:
type: string
responses:
'200':
description: Organization role unassigned from the user successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedRoleAssignmentResource'
'429':
$ref: '#/components/responses/TooManyRequests'
x-oaiMeta:
group: administration
examples:
request:
curl: "curl -X DELETE https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
response: "{\n \"object\": \"user.role.deleted\",\n \"deleted\": true\n}\n"
components:
schemas:
RoleListResource:
type: object
description: Paginated list of roles assigned to a principal.
properties:
object:
type: string
enum:
- list
description: Always `list`.
x-stainless-const: true
data:
type: array
description: Role assignments returned in the current page.
items:
$ref: '#/components/schemas/AssignedRoleDetails'
has_more:
type: boolean
description: Whether additional assignments are available when paginating.
next:
description: Cursor to fetch the next page of results, or `null` when there are no more assignments.
anyOf:
- type: string
- type: 'null'
required:
- object
- data
- has_more
- next
x-oaiMeta:
name: Assigned role list
example: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {},\n \"assignment_sources\": null\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n"
User:
type: object
description: Represents an individual `user` within an organization.
properties:
object:
type: string
enum:
- organization.user
description: The object type, which is always `organization.user`
x-stainless-const: true
id:
type: string
description: The identifier, which can be referenced in API endpoints
name:
anyOf:
- type: string
- type: 'null'
description: The name of the user
email:
anyOf:
- type: string
- type: 'null'
description: The email address of the user
role:
anyOf:
- type: string
- type: 'null'
description: '`owner` or `reader`'
added_at:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) of when the user was added.
is_default:
type: boolean
description: Whether this is the organization's default user.
created:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) of when the user was created.
user:
type: object
description: Nested user details.
properties:
object:
type: string
enum:
- user
x-stainless-const: true
id:
type: string
email:
anyOf:
- type: string
- type: 'null'
name:
anyOf:
- type: string
- type: 'null'
picture:
anyOf:
- type: string
- type: 'null'
enabled:
anyOf:
- type: boolean
- type: 'null'
banned:
anyOf:
- type: boolean
- type: 'null'
banned_at:
anyOf:
- type: integer
format: unixtime
- type: 'null'
required:
- object
- id
is_service_account:
type: boolean
description: Whether the user is a service account.
is_scale_tier_authorized_purchaser:
anyOf:
- type: boolean
- type: 'null'
description: Whether the user is an authorized purchaser for Scale Tier.
is_scim_managed:
type: boolean
description: Whether the user is managed through SCIM.
api_key_last_used_at:
anyOf:
- type: integer
format: unixtime
- type: 'null'
description: The Unix timestamp (in seconds) of the user's last API key usage.
technical_level:
anyOf:
- type: string
- type: 'null'
description: The technical level metadata for the user.
developer_persona:
anyOf:
- type: string
- type: 'null'
description: The developer persona metadata for the user.
projects:
anyOf:
- type: object
properties:
object:
type: string
enum:
- list
x-stainless-const: true
data:
type: array
items:
type: object
properties:
id:
anyOf:
- type: string
- type: 'null'
name:
anyOf:
- type: string
- type: 'null'
role:
anyOf:
- type: string
- type: 'null'
required:
- object
- data
- type: 'null'
description: Projects associated with the user, if included.
required:
- object
- id
- added_at
x-oaiMeta:
name: The user object
example: "{\n \"object\": \"organization.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n"
_MisalignmentErrorType:
anyOf:
- type: string
- type: string
enum:
- potentially_unintended_data_transfer
- potentially_unintended_data_access
- potentially_unintended_destructive_activity
- other
UserRoleAssignment:
type: object
description: Role assignment linking a user to a role.
properties:
object:
type: string
enum:
- user.role
description: Always `user.role`.
x-stainless-const: true
user:
$ref: '#/components/schemas/User'
role:
$ref: '#/components/schemas/Role'
required:
- object
- user
- role
x-oaiMeta:
name: The user role object
example: "{\n \"object\": \"user.role\",\n \"user\": {\n \"object\": \"organization.user\",\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711470000\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n}\n"
AssignedRoleDetails:
type: object
description: Detailed information about a role assignment entry returned when listing assignments.
properties:
id:
type: string
description: Identifier for the role.
name:
type: string
description: Name of the role.
permissions:
type: array
description: Permissions associated with the role.
items:
type: string
resource_type:
type: string
description: Resource type the role applies to.
predefined_role:
type: boolean
description: Whether the role is predefined by OpenAI.
description:
description: Description of the role.
anyOf:
- type: string
- type: 'null'
created_at:
description: When the role was created.
anyOf:
- type: integer
format: unixtime
- type: 'null'
updated_at:
description: When the role was last updated.
anyOf:
- type: integer
format: unixtime
- type: 'null'
created_by:
description: Identifier of the actor who created the role.
anyOf:
- type: string
- type: 'null'
created_by_user_obj:
description: User details for the actor that created the role, when available.
anyOf:
- type: object
additionalProperties: true
- type: 'null'
metadata:
description: Arbitrary metadata stored on the role.
anyOf:
- type: object
additionalProperties: true
- type: 'null'
assignment_sources:
description: Principals from which the role assignment is inherited, when available.
anyOf:
- type: array
items:
type: object
properties:
principal_id:
type: string
principal_type:
type: string
required:
- principal_id
- principal_type
- type: 'null'
required:
- id
- name
- permissions
- resource_type
- predefined_role
- description
- created_at
- updated_at
- created_by
- created_by_user_obj
- metadata
- assignment_sources
Role:
type: object
description: Details about a role that can be assigned through the public Roles API.
properties:
object:
type: string
enum:
- role
description: Always `role`.
x-stainless-const: true
id:
type: string
description: Identifier for the role.
name:
type: string
description: Unique name for the role.
description:
description: Optional description of the role.
anyOf:
- type: string
- type: 'null'
permissions:
type: array
description: Permissions granted by the role.
items:
type: string
resource_type:
type: string
description: Resource type the role is bound to (for example `api.organization` or `api.project`).
predefined_role:
type: boolean
description: Whether the role is predefined and managed by OpenAI.
required:
- object
- id
- name
- description
- permissions
- resource_type
- predefined_role
x-oaiMeta:
name: The role object
example: "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n"
PublicAssignOrganizationGroupRoleBody:
type: object
description: Request payload for assigning a role to a group or user.
properties:
role_id:
type: string
description: Identifier of the role to assign.
required:
- role_id
x-oaiMeta:
example: "{\n \"role_id\": \"role_01J1F8ROLE01\"\n}\n"
_MisalignmentSteer:
properties:
message:
type: string
description: The public continuation instruction.
type: object
required:
- message
Error:
type: object
properties:
code:
anyOf:
- type: string
- type: 'null'
message:
type: string
param:
anyOf:
- type: string
- type: 'null'
type:
type: string
misalignment:
$ref: '#/components/schemas/MisalignmentErrorDetailsResource'
required:
- type
- message
- param
- code
ErrorResponse:
type: object
properties:
error:
$ref: '#/components/schemas/Error'
required:
- error
DeletedRoleAssignmentResource:
type: object
description: Confirmation payload returned after unassigning a role.
properties:
object:
type: string
description: Identifier for the deleted assignment, such as `group.role.deleted` or `user.role.deleted`.
deleted:
type: boolean
description: Whether the assignment was removed.
required:
- object
- deleted
x-oaiMeta:
name: Role assignment deletion confirmation
example: "{\n \"object\": \"group.role.deleted\",\n \"deleted\": true\n}\n"
MisalignmentErrorDetailsResource:
properties:
error_type:
$ref: '#/components/schemas/_MisalignmentErrorType'
description: An optional classification; clients must accept additional values.
detailed_explanation:
type: string
description: The public explanation for this block.
steer:
$ref: '#/components/schemas/_MisalignmentSteer'
description: An optional public continuation instruction.
type: object
required: []
responses:
TooManyRequests:
description: The request was rejected because a rate limit was exceeded.
headers:
Retry-After:
description: The minimum number of seconds to wait before retrying. This header is returned when the server has computed a retry delay and may be omitted for 429 responses that require user action.
schema:
type: integer
minimum: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
AdminApiKeyAuth:
type: http
scheme: bearer
x-oaiMeta:
navigationGroups:
- id: responses
title: Responses API
- id: webhooks
title: Webhooks
- id: endpoints
title: Platform APIs
- id: vector_stores
title: Vector stores
- id: chatkit
title: ChatKit
beta: true
- id: containers
title: Containers
- id: live
title: Live (alpha)
- id: realtime
title: Realtime
- id: chat
title: Chat Completions
- id: assistants
title: Assistants
deprecated: true
- id: administration
title: Administration
- id: legacy
title: Legacy
groups:
- id: responses-streaming
title: Streaming events
description: 'When you [create a Response](https://developers.openai.com/api/reference/resources/responses/methods/create) with
`stream` set to `true`, the server will emit server-sent events to the
client as the Response is generated. This section contains the events that
are emitted by the server.
When processing a `compaction_trigger`, `response.compaction.compacting`
reports newly sampled summary output at most once every 30 seconds. It
carries no summary content and does not modify the compaction output item.
The existing `response.output_item.added` and `response.output_item.done`
events mark that item''s lifecycle; `response.output_item.done` carries its
final encrypted content. A short compaction may finish without emitting a
progress event.
[Learn more about streaming responses](https://developers.openai.com/api/docs/guides/streaming-responses).
'
navigationGroup: responses
sections:
- type: object
key: ResponseCreatedEvent
path: <auto>
- type: object
key: ResponseInProgressEvent
path: <auto>
- type: object
key: ResponseCompletedEvent
path: <auto>
- type: object
key: ResponseFailedEvent
path: <auto>
- type: object
key: ResponseIncompleteEvent
path: <auto>
- type: object
key: ResponseOutputItemAddedEvent
path: <auto>
- type: object
key: ResponseOutputItemDoneEvent
path: <auto>
- type: object
key: ResponseCompactionCompactingEvent
path: <auto>
- type: object
key: ResponseContentPartAddedEvent
path: <auto>
- type: object
key: ResponseContentPartDoneEvent
path: <auto>
- type: object
key: ResponseTextDeltaEvent
path: response/output_text/delta
- type: object
key: ResponseTextDoneEvent
path: response/output_text/done
- type: object
key: ResponseRefusalDeltaEvent
path: <auto>
- type: object
key: ResponseRefusalDoneEvent
path: <auto>
- type: object
key: ResponseFunctionCallArgumentsDeltaEvent
path: <auto>
- type: object
key: ResponseFunctionCallArgumentsDoneEvent
path: <auto>
- type: object
key: ResponseFileSearchCallInProgressEvent
path: <auto>
- type: object
key: ResponseFileSearchCallSearchingEvent
path: <auto>
- type: object
key: ResponseFileSearchCallCompletedEvent
path: <auto>
- type: object
key: ResponseWebSearchCallInProgressEvent
path: <auto>
- type: object
key: ResponseWebSearchCallSearchingEvent
path: <auto>
- type: object
key: ResponseWebSearchCallCompletedEvent
path: <auto>
- type: object
key: ResponseReasoningSummaryPartAddedEvent
path: <auto>
- type: object
key: ResponseReasoningSummaryPartDoneEvent
path: <auto>
- type: object
key: ResponseReasoningSummaryTextDeltaEvent
path: <auto>
- type: object
key: ResponseReasoningSummaryTextDoneEvent
path: <auto>
- type: object
key: ResponseReasoningTextDeltaEvent
path: <auto>
- type: object
key: ResponseReasoningTextDoneEvent
path: <auto>
- type: object
key: ResponseImageGenCallCompletedEvent
path: <auto>
- type: object
key: ResponseImageGenCallGeneratingEvent
path: <auto>
- type: object
key: ResponseImageGenCallInProgressEvent
path: <auto>
- type: object
key: ResponseImageGenCallPartialImageEvent
path: <auto>
- type: object
key: ResponseMCPCallArgumentsDeltaEvent
path: <auto>
- type: object
key: ResponseMCPCallArgumentsDoneEvent
path: <auto>
- type: object
key: ResponseMCPCallCompletedEvent
path: <auto>
- type: object
key: ResponseMCPCallFailedEvent
path: <auto>
- type: object
key: ResponseMCPCallInProgressEvent
path: <auto>
- type: object
key: ResponseMCPListToolsCompletedEvent
path: <auto>
- type: object
key: ResponseMCPListToolsFailedEvent
path: <auto>
- type: object
key: ResponseMCPListToolsInProgressEvent
path: <auto>
- type: object
key: ResponseCodeInterpreterCallInProgressEvent
path: <auto>
- type: object
key: ResponseCodeInterpreterCallInterpretingEvent
path: <auto>
- type: object
key: ResponseCodeInterpreterCallCompletedEvent
path: <auto>
- type: object
key: ResponseCodeInterpreterCallCodeDeltaEvent
path: <auto>
- type: object
key: ResponseCodeInterpreterCallCodeDoneEvent
path: <auto>
- type: object
key: ResponseOutputTextAnnotationAddedEvent
path: <auto>
- type: object
key: ResponseQueuedEvent
path: <auto>
- type: object
key: ResponseCustomToolCallInputDeltaEvent
path: <auto>
- type: object
key: ResponseCustomToolCallInputDoneEvent
path: <auto>
- type: object
key: ResponseErrorEvent
path: <auto>
- id: responses-websocket-client-events
title: Client events
description: 'Events sent by the client over a Responses API WebSocket connection.
'
navigationGroup: responses
sections:
- type: object
key: ResponsesClientEventResponseCreate
path: <auto>
- type: object
key: ResponseSteerEvent
path: <auto>
- id: responses-websocket-server-events
title: Server events (WebSocket only)
description: 'Events emitted only over a Responses API WebSocket connection.
'
navigationGroup: responses
sections:
- type: object
key: ResponseSteerAcceptedEvent
path: <auto>
- type: object
key: ResponseSteerPendingEvent
path: <auto>
- type: object
key: ResponseSteerFailedEvent
path: <auto>
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-user-organization-role-assignments-api-openapi.yml