OpenAI API (unofficial showcase)
POST/organization/roles

Create an organization role

Creates a custom role for the organization. Provide role_name and permissions; you can also include an optional description. The response includes the new role's identifier, permissions, and resource type.

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

3 body fields

Payload for creating a custom organization role. Include role_name and permissions; description is optional.

role_namestringrequired
Unique name for the role.
permissionsarray<string>required
Permissions to grant to the role.
descriptionstringoptional
Optional description of the role.

5 status codes
200Returns the created role object with its identifier, name, description, granted 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. Include both role_name and permissions in the request body.