Developer Portal for YouTrack and Hub Help

Users

This resource provides access to users in Hub and YouTrack.

Resource

<Hub Service URL>/api/rest/users

Returned entity

User. For the description of the entity attributes, see User Attributes.

Supported methods

Supported sub-resources

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: 8 February 2024