Manage Roles and Permissions

Send the following request to browse roles:

GET
/app/rest/roles

The response is the Roles object that contains Role instances.

If you need to obtain all existing roles and view their parent-child relationships, use the following request:

GET
/app/rest/roles?fields=role(id,name,included(role(id,name)))

One specific role can be obtained using the role ID:

GET
/app/rest/roles/id:PROJECT_DEVELOPER

To create a new role, send the POST request with a Role object as a body to the /app/rest/roles endpoint. Sample payload (XML):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<role name="New Role 2">
    <included><role id="PROJECT_VIEWER" name="Project viewer"/></included>
    <permissions>
        <permission id="customize_build_parameters" global="false"/>
    </permissions>
</role>

To remove a role, send the DELETE request to the /app/rest/roles/id:id endpoint:

DELETE
/app/rest/roles/id:NEW_EMPTY_ROLE

To add and remove permissions, you need their IDs. You can browse permissions of the system administrator role to view all avialable permissions and their IDs:

GET
/app/rest/roles/id:SYSTEM_ADMIN?fields=permissions(permission)

Then you can use these IDs to add and remove permissions to/from existing roles:

PUT
/app/rest/roles/id:NEW_ROLE_2/permissions/comment_build

DELETE
/app/rest/roles/id:NEW_ROLE_2/permissions/comment_build

Instead of adding individual permissions one-by-one, you can add include group A into the included parameter of group B. As a result, all permissions available for group A will also be available for group B.

PUT
/app/rest/roles/id:NEW_REST_ROLE/included/PROJECT_DEVELOPER

DELETE
/app/rest/roles/id:NEW_REST_ROLE/included/PROJECT_DEVELOPER