Sample - OpenAI API
POST/organization/roles

Create an organization role

Creates a custom role for the organization. Supply role_name and permissions, and optionally provide a description for the role.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

3 body fields

Custom organization role definition containing its name, permissions, and optional description.

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

2 status codes
200Returns the created role with its identifier, name, description, permissions, resource type, and predefined-role status.
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.
429Returned when the request was rejected because the rate limit was exceeded.
errorobjectrequired

Error handling

A 429 is returned when the request exceeds the rate limit. role_name and permissions are required, and role_name must be unique; permissions must contain permission strings.