Developer Portal for YouTrack and Hub Help

Users, Groups, and Access Management

This page explains how to work with users, groups, and roles using the YouTrack REST API and the Hub REST API, and when to use each.

YouTrack and Hub Services

Any YouTrack instance as a product contains two services:

  • YouTrack service — the issue tracker itself.

  • Hub service — the authorization and authentication service that also manages user accounts and everything that relates to access management.

YouTrack REST API vs Hub REST API

Starting with YouTrack 2026.1, YouTrack REST API supports user, group, and access management operations directly. Hub REST API remains fully supported and is not going away — it is now an alternative approach rather than the only option.

Use YouTrack REST API when:

  • You are on YouTrack 2026.1 or later and want to keep all your API calls within a single service.

  • You are already working with the YouTrack REST API and want to avoid switching to a separate Hub endpoint.

Use Hub REST API when:

  • You are on a YouTrack version earlier than 2026.1.

  • You need to work with credentials, tokens, 2FA settings, keys, or certificates.

The following table maps entities to the corresponding endpoints in each API:

Entity

YouTrack REST API (2026.1+) Endpoints

Hub REST API Endpoints

Users

<YouTrack_REST_API_URL>/users and related endpoints

<YouTrack_REST_API_URL>/users/{id}

<Hub_REST_API_URL>/users and related endpoints

Groups

<YouTrack_REST_API_URL>/groups and related endpoints

<YouTrack_REST_API_URL>/groups/{id}

<Hub_REST_API_URL>/usergroups and related endpoints

Roles

<YouTrack_REST_API_URL>/roles

<YouTrack_REST_API_URL>/roles/{id}

<Hub_REST_API_URL>/roles and related endpoints

Roles assigned to specific users or groups

<YouTrack_REST_API_URL>/assignedRoles

<YouTrack_REST_API_URL>/assignedRoles/{id}

<Hub_REST_API_URL>/users/{id}/projectroles and related endpoints

Permissions

<YouTrack_REST_API_URL>/permissions

<Hub_REST_API_URL>/permissions and related endpoints

Organizations

<YouTrack_REST_API_URL>/admin/organizations

<YouTrack_REST_API_URL>/admin/organizations/{id}

<Hub_REST_API_URL>/org and related endpoints

Find a YouTrack User in Hub

When you need to perform a user management operation via Hub REST API, you first need to find the Hub user account that corresponds to the target YouTrack user profile. Follow the steps below.

In general, this procedure contains two steps:

  1. Get the key attributes of the target YouTrack user: login, email, ringId. You can use any of these attributes to find the required user account in Hub.

    You can use any of the following endpoints:

    • <YouTrack_REST_API_URL>/users?fields=login,email,name,ringId

    • <YouTrack_REST_API_URL>/users/{login}?fields=login,email,name,ringId, if you know the login of the target user.

    • <YouTrack_REST_API_URL>/users/{id}?fields=login,email,name,ringId, if you already know the entity ID of the target user.

  2. To find the target user account in Hub, you need to get the list of users and filter it using the query request parameter with the name of the Hub entity attribute and the value of the relevant YouTrack entity attribute:

    YouTrack entity attribute

    Hub entity attribute

    login

    login

    email

    email

    ringId

    id

    To get the list of users in Hub, use the following endpoint:

    <Hub_REST_API_URL>/users?query=[login:user_login|email:user_email|id:ringId_value]

Sample procedure

Here's a list of sample calls to illustrate the procedure.

To start, let's get the key attributes of a user with the login "jane.doe":

curl --location --request GET 'https://example.youtrack.cloud/api/users/jane.doe?fields=id,login,name,email,ringId' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7'

In response we get the following JSON object:

{ "email": "jane.doe@example.com", "ringId": "90704ebe-c211-4906-a328-4f16ca82a5ea", "name": "Jane Doe", "login": "jane.doe", "id": "1-3", "$type": "User" }

Now, let's find this user account in Hub. For the sample purpose we use all three variants of the query. In real life, you can use any of them. Using the ringId gives the most reliable results.

  1. Filter by the ringId value:

    curl --location --request GET 'https://example.youtrack.cloud/hub/api/rest/users?query=id:90704ebe-c211-4906-a328-4f16ca82a5ea&fields=login,id,name,profile(email)' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer perm:cm9vdA==.QWRtaW4gUmVzdCBBUEkgRG9jcw==.OcsxZrnZnBZhyWaGE0Uz1OiA5bRVNt'

  2. Filter by the login value:

    curl --location --request GET 'https://example.youtrack.cloud/hub/api/rest/users?query=login:jane.doe&fields=login,id,name,profile(email)' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer perm:cm9vdA==.QWRtaW4gUmVzdCBBUEkgRG9jcw==.OcsxZrnZnBZhyWaGE0Uz1OiA5bRVNt'

  3. Filter by the email value:

    curl --location --request GET 'https://example.youtrack.cloud/hub/api/rest/users?query=email:jane.doe@example.com&fields=login,id,name,profile(email)' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer perm:cm9vdA==.QWRtaW4gUmVzdCBBUEkgRG9jcw==.OcsxZrnZnBZhyWaGE0Uz1OiA5bRVNt'

All these requests produce the same result, returning the following data in the response:

{ "skip": 0, "top": 100, "total": 1, "queriedSingleton": true, "users": [ { "type": "user", "id": "90704ebe-c211-4906-a328-4f16ca82a5ea", "name": "Jane Doe", "login": "jane.doe", "profile": { "email": { "type": "EmailJSON", "verified": true, "email": "jane.doe@example.com" } } } ] }
01 April 2026
PaginationPostman Collection for the YouTrack REST API