Manage Roles and Permissions

This article explains how to manage TeamCity roles and permissions via REST API.

Browse All Roles

Send the following request to browse roles:

/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:

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

One specific role can be obtained using the role ID:

/app/rest/roles/id:PROJECT_DEVELOPER

Add and Remove Roles

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:

/app/rest/roles/id:NEW_EMPTY_ROLE

Add and Remove Individual Permissions

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:

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

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

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

Add and Remove Included Roles

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.

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

Last modified: 04 May 2023