TeamCity REST API Reference 2024.07 Help

Manage Users

This article lists REST API requests concerning users.

Get Users

To get a list of all users, send:

/app/rest/users

The endpoint responds with a Users entity which contains instances of a User entity.

Get Specific User Details

/app/rest/users/<userLocator>

Here, userLocator is typed as UserLocator. For example, to get a user by username, send:

/app/rest/users/username:MyUsername

Get Current User

To get the entity of the currently authenticated user, send:

/app/rest/users/current

Here, current is a dimension of UserLocator.

Create User

To create a user, POST a User entity to:

/app/rest/users

Example payload:

<user email="string" name="string" username="string" password="string"> <roles> <role roleId="SYSTEM_ADMIN" scope="g"/> </roles> <groups> <group key="MyCustomGroupKey"/> </groups> </user>
{ "username": "username", "password": "password", "email": "email", "roles": { "role": [ { "roleId": "SYSTEM_ADMIN", "scope": "g", } ] }, "groups": { "group": [ { "key": "MyCustomGroupKey" } ] } }

Update/Remove Specific User

To update a user definition, PUT an updated User entity to:

/app/rest/users/<userLocator>

To delete a user, use:

/app/rest/users/<userLocator>

Handle Groups

To retrieve groups for a specific user, run the following request:

/app/rest/users/<userLocator>/groups

To update the group ownership, send an updated Groups entity to:

/app/rest/users/<userLocator>/groups

Example payload:

<groups> <group key="MyCustomGroupKey"/> </groups>
{ "group": [ { "key": "MyCustomGroupKey" } ] }

To delete user from a given group, use:

/app/rest/users/{userLocator}/groups/{groupLocator}

Here, groupLocator is typed as UserGroupLocator.

Manage User Roles

To get user roles for a specific user, run the following request:

/app/rest/users/<userLocator>/roles

Similarly to updating the user entity, you can update them all by sending a PUT request:

/app/rest/users/<userLocator>/roles

Example payload:

<roles> <role roleId="SYSTEM_ADMIN" scope="g"/> </roles>
{ "role": [ { "roleId": "SYSTEM_ADMIN", "scope": "g", } ] }

Alternatively, you can add a new role by this PUT request:

/app/rest/users/{userLocator}/roles/<roleId>/<scope>

or delete an existing role:

/app/rest/users/{userLocator}/roles/<roleId>/<scope>

Manage Access Tokens

User can create tokens only for own account, regardless of their level of permissions. To get a list of owned tokens, send:

/app/rest/users/<userLocator>/tokens

To create a new access token, send:

/app/rest/users/<userLocator>/tokens/<tokenName>

To delete an access token, send:

/app/rest/users/<userLocator>/tokens/<tokenName>
Last modified: 29 March 2022