POST
/projects/{project_id}/rolesCreate a project role
Creates a custom role for a project with a unique name and a set of permissions. Supply role_name and permissions; you can also provide a description for the role.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
project_idstringrequired
The ID of the project in which to create the role.
Parameters for the custom project role. Include the required role name and permissions; the 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.
200Returns the created role with its identifier, name, description, granted permissions, resource type, and predefined status.
objectstringrequired
Always `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 you do 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 operation cannot be performed, and a 403 is returned when you lack permission. A 404 is returned when the endpoint is unavailable or a requested resource is not found; a 429 is returned when the rate limit is exceeded. The project_id path parameter must identify the project, and role_name and permissions are required in the body.