Manage Roles and Permissions
This article explains how to manage TeamCity roles and permissions via REST API.
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
Thanks for your feedback!