OpenAI API (unofficial showcase)
POST/organization/roles/{role_id}

Update an organization role

Updates an existing organization role. Use role_id to identify the role and provide any of permissions, description, or role_name to change those values. The response contains the updated role details.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
role_idstringrequired
The unique identifier of the role to update.

Fields to update on the role. You can provide permissions, description, role_name, or any combination of them.

permissionsarray<string>optional
Updated set of permissions for the role.
descriptionstringoptional
New description for the role.
role_namestringoptional
New name for the role.

5 status codes
200Returns the updated role object with its identifier, name, description, permissions, resource type, and whether it is predefined.
objectstringrequired
Always `role`.
Allowed:role
idstringrequired
Identifier for the role.
namestringrequired
Unique name for the role.
descriptionstringrequired
Optional description of the role.
permissionsarray<string>required
Permissions granted by the role.
resource_typestringrequired
Resource type the role is bound to (for example `api.organization` or `api.project`).
predefined_rolebooleanrequired
Whether the role is predefined and managed by OpenAI.
400Returned when the request parameters are invalid or the requested operation cannot be performed.
errorobjectrequired
403Returned when the caller does not have permission to perform this operation.
errorobjectrequired
Details about the permission error.
404Returned when the endpoint is unavailable or a requested resource is not found in the organization or project.
errorobjectrequired
429Returned when the request is rejected because a rate limit was exceeded.
errorobjectrequired

Error handling

A 400 is returned when the request parameters are invalid or the requested operation cannot be performed. A 403 is returned when the authenticated user does not have permission, a 404 when the endpoint is unavailable or a requested resource is not found, and a 429 when a rate limit is exceeded. The role_id path parameter identifies the role to update; permissions, description, and role_name are optional body fields.