# 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 available for Hub-specific operations, but YouTrack REST API is the recommended API for managing YouTrack users, groups, roles, and permissions. 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](resource-api-users.html) and related endpoints [<YouTrack_REST_API_URL>/users/{id}](operations-api-users.html) | [<Hub_REST_API_URL>/users](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html) and related endpoints | | Groups | [<YouTrack_REST_API_URL>/groups](resource-api-groups.html) and related endpoints [<YouTrack_REST_API_URL>/groups/{id}](operations-api-groups.html) | [<Hub_REST_API_URL>/usergroups](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html) and related endpoints | | Roles | [<YouTrack_REST_API_URL>/roles](resource-api-roles.html) [<YouTrack_REST_API_URL>/roles/{id}](operations-api-roles.html) | [<Hub_REST_API_URL>/roles](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html) and related endpoints | | Roles assigned to specific users or groups | [<YouTrack_REST_API_URL>/assignedRoles](resource-api-assignedRoles.html) [<YouTrack_REST_API_URL>/assignedRoles/{id}](operations-api-assignedRoles.html) | [<Hub_REST_API_URL>/users/{id}/projectroles](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html) and related endpoints | | Permissions | [<YouTrack_REST_API_URL>/permissions](resource-api-permissions.html) | [<Hub_REST_API_URL>/permissions](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html) and related endpoints | | Organizations | [<YouTrack_REST_API_URL>/admin/organizations](resource-api-admin-organizations.html) [<YouTrack_REST_API_URL>/admin/organizations/{id}](operations-api-admin-organizations.html) | [<Hub_REST_API_URL>/org](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html) and related endpoints | > **Tip:** > For a full reference of the Hub REST API methods, see the [Hub REST API reference](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html). ## Find a YouTrack User in Hub > **Note:** > This section is relevant if you are using a YouTrack version earlier than 2026.1. Starting with YouTrack 2026.1, you can work with user data directly via YouTrack REST API without needing to look up the corresponding Hub account. 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: * `/users?fields=login,email,name,ringId` * `/users/{login}?fields=login,email,name,ringId`, if you know the login of the target user. * `/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: `/users?query=[login:user_login|email:user_email|id:ringId_value]` > **Tip: YouTrack and Hub Base URL** > These base URLs that we mentioned are the base URLs of the YouTrack service and Hub service respectively. For example, if you use a YouTrack Cloud instance: > > > > * `https://example.youtrack.cloud` > > * `https://example.youtrack.cloud/hub` > > > > If you use a YouTrack Server installation: > > > > * `https://companyname.com` > > * `https://companyname.com/hub` > > > > Read more details about [Hub REST API URL](https://www.jetbrains.com.cn/en-us/help/hub/Hub-Rest-Api-URL.html) and [YouTrack REST API URL](api-url-and-endpoints.html). ### 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 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: ```JSON { "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. > **Note:** > Please note that in Hub REST API, server returns all attributes of an entity, by default. Use the `fields` parameter to explicitly specify the attributes that you wish to get in the response. Read more about [Hub > Partial Requests](https://www.jetbrains.com.cn/en-us/help/hub/Hub-REST-API.html). 1. Filter by the `ringId` value: ```CURL 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 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 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: ```JSON { "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" } } } ] } ```