Users, Groups, and Access Management

We recommend the YouTrack REST API to find and manage users, groups, roles, and permissions as part of a YouTrack integration. Migrate existing Hub REST API calls for this purpose to the corresponding YouTrack endpoints.

YouTrack and Hub Services

YouTrack uses two services:

The YouTrack service provides issue tracking and the REST API for working with YouTrack data, including users, groups, and access management.
The Hub service provides authentication and authorization.

YouTrack REST API vs Hub REST API

Starting with YouTrack 2026.1, the YouTrack REST API supports user, group, and access management operations directly. Use this API for YouTrack data and access management.

For replacement endpoints and a procedure for updating existing integrations, see Migrate from the Hub REST API to the YouTrack REST API. The examples below show how to find users and groups directly in YouTrack.

Hub REST API endpoints for YouTrack projects, project teams, and organizations are no longer available for YouTrack data starting with YouTrack 2026.1. For details, see Hub REST API Endpoints and Entities Deprecated in YouTrack 2026.1.

You can continue using Hub for standalone identity and group lookups, even when a corresponding YouTrack endpoint exists. There is no migration deadline.

Use the Hub REST API for operations that are specific to Hub and aren't available in the YouTrack REST API, such as managing Hub credentials, keys, or certificates. For these operations and for user and group management in YouTrack versions earlier than 2026.1, see the Hub REST API reference.

The following table lists corresponding resources. Supported operations and permissions can differ between the APIs:

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}` For role assignment filters and examples, see Access Management Query Syntax.	`<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 These endpoints do not provide YouTrack organization data starting with YouTrack 2026.1.

For permanent token authentication and token management in the user profile, see Manage Permanent Tokens.

Find Users in YouTrack

To find a user, send a GET request to /api/users with the query parameter. For example, search for users whose login or name starts with jane:

        curl --get 'https://example.youtrack.cloud/api/users' \
          --data-urlencode 'query=jane' \
          --data-urlencode 'fields=id,login,name' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer <permanent_token>'
    

If you already know the user's login or YouTrack entity ID, request the user directly:

GET /api/users/jane.doe?fields=id,login,name

Use the returned id for subsequent YouTrack REST API requests involving this user. You don't need to look up the corresponding Hub account. For supported attributes and operations, see Users and Operations with Specific User.

Search Users by Email or Group Membership

For structured user searches, pass your query in the searchQuery parameter to /api/users. Use this parameter for email lookup and group inclusion or exclusion:

Find	`searchQuery` value
A user with a specific email address	`email: {jane.doe@example.com}`
Members of a group	`in: 23-1`
Users outside a group	`not in: 23-1`

Replace 23-1 with the group's YouTrack ID. Group membership searches require read access to the group. All results are subject to your access to user data.

For example, find a user by email:

        curl --get 'https://example.youtrack.cloud/api/users' \
          --data-urlencode 'searchQuery=email: {jane.doe@example.com}' \
          --data-urlencode 'fields=id,login,name,email' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer <permanent_token>'
    

Use query for the simple name searches shown above and searchQuery for structured user searches. Do not combine these parameters in the same request to /api/users.

Find Groups in YouTrack

To find a group, send a GET request to /api/groups with the query parameter. For example, search for groups whose name starts with Support:

        curl --get 'https://example.youtrack.cloud/api/groups' \
          --data-urlencode 'query=Support' \
          --data-urlencode 'fields=id,name' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer <permanent_token>'
    

Use the returned id in requests to /api/groups/{id} and its sub-resources. For supported attributes, operations, and required permissions, see User Groups and Operations with Specific UserGroup.

User and group searches respect YouTrack permissions and visibility settings. When retrieving lists, use $top and $skip to page through results. For details, see Pagination.

Migrate Existing Hub REST API Calls

For integrations that work with YouTrack data and access management, migrate Hub REST API calls to the YouTrack REST API. Follow Migrate from the Hub REST API to the YouTrack REST API to update endpoints, authentication, searches, entity IDs, and response handling.

Match a YouTrack User with a Hub Account

If your integration needs both YouTrack data and a Hub-specific operation, use the user's ringId to match the accounts. This optional step applies to any YouTrack version where your integration uses both services.

To find the matching Hub account:

Request the YouTrack user's ringId. For example, if you know the user's login:
GET /api/users/jane.doe?fields=id,login,ringId
Use the returned ringId as the user ID in a direct request to Hub. For a built-in Hub service:
GET /hub/api/rest/users/{ringId}?fields=id,login,name
For a standalone Hub service, use its REST API base URL. The request requires access to the user in Hub.

For user and group operations performed entirely in YouTrack, use the YouTrack id directly. Groups also expose a ringId for correlation with Hub when available.

04 November 2026