Users

This resource provides access to users in Hub and YouTrack.

Resource	<Hub Service URL>/api/rest/users For details and examples of Hub Service URLs, see Hub REST API URL.
Returned entity	User. For the description of the entity attributes, see User Attributes.
Supported methods	`GET`: Read a List of Users. `POST`: Add a New User.
Supported sub-resources	/users/{userID}: Operations with a Specific User /users/{userID}/groups: Groups of a Specific User /users/{userID}/userdetails: User Details of a Specific User /users/{userID}/projectroles: Project Roles of a Specific User

User Attributes

Represents a user in Hub and YouTrack.

Attributes

This table describes attributes of the User entity.

To receive an attribute in the response from the server, specify it explicitly in the fields request parameter.
To update an attribute, provide it in the body of a POST request.

Field	Type	Description
id	String	The unique identifier of the user. `Read-only`.
aliases	Set.<alias>	The set of IDs of user accounts that have been merged into this account.
avatar	avatar	The avatar of the user.
banned	Boolean	This flag indicates whether the user account is banned. `true` when the account is banned, otherwise `false`.
creationTime	Long	The timestamp when the user account was created.
details	Set.<details>	A set of login credentials associated with the account. These credentials point to various built-in and federated authentication modules.
groups	Set.<userGroup>	The list of groups where the user belongs.
guest	Boolean	This flag indicates whether the user account is the guest account. `true` when the account is guest, otherwise `false`.
lastAccessTime	Long	The timestamp when the user account last logged in to the system.
licenses	Set.<license>	The list of licenses that the user has.
login	String	The login of the user.
name	String	The full name of the user.
permanentTokens	Set.<permanentToken>	The list of permanent tokens of the user.
profile	profile	The user profile details, such as email, locale preferences, and custom user attributes.
favoriteProjects	Set.<project>	The set of favourite projects of the user.
projectRoles	Set.<projectRole>	The set of project roles that this user has been granted directly.
teams	Set.<projectTeam>	The list of project teams where the user belongs.
type	String	The type of the entity. In this case, it's `user`.
userType	userType	The type of the user account.
VCSUserNames	Set.<vcsUserName>	The list of VCS usernames of the user.

Read a List of Users

Get all users that match the specified query.

Request Syntax

GET <Hub Service URL>/api/rest/users?{fields}&{$top}&{$skip}&{query}&{orderBy}

Request Parameters

Parameter	Type	Description
fields	String	Optional. Returns only the specified subset of the fields for each user. Use Fields Syntax to define the subset.
$skip	Int	Optional. Lets you set a number of returned entities to skip before returning the first one.
$top	Int	Optional. Lets you specify the maximum number of Users that are returned in the response.
query	String	Optional. Lets you specify a search query to filter the returned results. See Query Syntax for the definition of supported logical operations syntax. For the User fields and tuples, see Hub REST API Reference.
orderBy	String	Optional Returns the list of Users sorted by a specified field. See Sorting Syntax for details. Users support ordering by the following fields: `creationTime`, `lastAccessTime`, `login`, `name`, `username`.

Sample

Request

                    https://example.youtrack.cloud/hub/api/rest/users?fields=id,login,banned,banReason,banBadge,guest,creationTime,lastAccessTime
                

Response Body

                    {
                    "type": "UsersPage",
                    "skip": 0,
                    "top": 100,
                    "total": 7,
                    "users": [
                    {
                    "type": "user",
                    "id": "7835f294-dc19-4082-8d43-e69180f33fe6",
                    "login": "guest",
                    "banned": true,
                    "banBadge": "banned",
                    "guest": true,
                    "creationTime": 1470655545290
                    },
                    {
                    "type": "user",
                    "id": "c498bf43-ab05-456f-9b36-a9fe0cad45c9",
                    "login": "john.smith",
                    "banned": false,
                    "guest": false,
                    "creationTime": 1470657759060,
                    "lastAccessTime": 1695735974508
                    },
                    {
                    "type": "user",
                    "id": "329d31a1-352f-48b7-a454-6845300b7e7d",
                    "login": "Donna_Noble",
                    "banned": true,
                    "guest": false,
                    "creationTime": 1479283868539
                    },
                    {
                    "type": "user",
                    "id": "69470fbf-da3b-4a7a-89f7-6ec8c68c9c1c",
                    "login": "Matt_Jones",
                    "banned": true,
                    "guest": false,
                    "creationTime": 1492511005817
                    },
                    {
                    "type": "user",
                    "id": "a896bd2c-9f37-468d-9cc2-3c0dbfef841b",
                    "login": "David_Tennant",
                    "banned": true,
                    "guest": false,
                    "creationTime": 1501836567299
                    },
                    {
                    "type": "user",
                    "id": "564c8a99-e20c-4813-a52c-4aa5225d35f4",
                    "login": "Peter_Capaldi",
                    "banned": true,
                    "guest": false,
                    "creationTime": 1501836600157
                    },
                    {
                    "type": "user",
                    "id": "7a0573d6-a39e-4724-80e7-091acb8d2c99",
                    "login": "william.johnson",
                    "banned": false,
                    "guest": false,
                    "creationTime": 1645019022409
                    }
                    ]
                    }
                

Add a New User

Create a user.

Required fields: login.

Request Syntax

POST <Hub Service URL>/api/rest/users?fields=string

Request Parameters

Parameter	Type	Description
fields	String	A list of User attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.

Sample

In this example, we create a standard user account with the login william.johnson.

Request

https://example.youtrack.cloud/hub/api/rest/users?fields=id,login

Request Body

              {
                "login": "william.johnson",
                "banned": false,
                "profile": {
                  "email": {
                    "email": "will@johnson.com",
                    "verified": true
                  }
                }
              }
            

Response Body

                {
                      "type": "user",
                      "id": "57001ba9-94b0-44a3-938d-3a5197a7c29f",
                      "login": "william.johnson"
                  }
            

Last modified: 7 November 2024