Add User to Project Team

Last modified: 21 March 2025

Use case

Add users to a project team using REST API.

Summary

To begin with, you cannot add users to a project team with YouTrack's REST API. Operations with users, groups, teams and access management are covered by Hub REST API. This means, that you need to use not YouTrack but Hub service REST API endpoints to solve this task.

Before you add a user to a project team, you need to collect the following data:

  • The entity ID of the project in Hub.

  • The entity ID in Hub of the user that you add to the project team.

These mentioned entity IDs in Hub are represented by the ringId attribute of YouTrack's entities "user" and "projects". Hence, by requesting this attribute for target user and project, you will get the target IDs for Hub REST API.

When you have all necessary entity IDs, you can add the user to the target project team by sending a POST request to the following endpoint:

Step-by-Step

To add a user to a project team:

  1. Get Hub entity ID of the target YouTrack project.

    To do so, send GET request to the /api/admin/projects endpoint, and in the fields request parameter, list ringId (represents the Hub entity ID in YouTrack REST API entity), shortName and name to identify the project. If you know the shortName or name of the target project, you can specify it in the query parameter to narrow down the results returned from the server.

    For example:

    curl -L -X GET 'https://example.youtrack.cloud/api/admin/projects?fields=id,name,shortName,ringId&query=SP' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cookie: JSESSIONID=node0me8f20cnn11hg7zes33twvmc630.node0'

    In response, server returned the following data:

    [
  {
    "shortName": "SP",
    "ringId": "c07dbc32-c2f9-4189-8ae2-3375f6aa1702",
    "name": "Sample Project",
    "id": "0-0",
    "$type": "Project"
  }
]

  2. Get Hub entity ID of the target YouTrack user.

    To do so, send GET request to the /api/users endpoint, and in the fields request parameter, list ringId (represents the Hub entity ID in YouTrack REST API entity), login and name to identify the user. If you know the login or name of the target user, you can specify it in the query parameter to narrow down the results returned from the server.

    For example:

    curl -L -X GET 'https://example.youtrack.cloud/api/users?fields=id,ringId,name,login&query=Mad%20Max' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cookie: JSESSIONID=node0mvgm5m4rifm11cxhwzedm6azu621.node0'

    In response, server returned the following data:

    [
  {
    "ringId": "e6446bd8-7fec-430e-bc62-54c4e7a231b6",
    "login": "Mad_Max",
    "name": "Mad Max",
    "id": "1-7",
    "$type": "User"
  }
]

    Now that we have Hub entity IDs for both target project and user, we can move to the last step.

  3. Add user to the project's team.

    To do so, you need to send POST request to the following Hub REST API endpoint:

    [Hub_service_baseURL]/api/rest/projects/[projectId=ringId]/team/users

    In the payload of the request, you need to specify the user's ringId.

    For example:

    curl -L -X POST 'https://example.youtrack.cloud/hub/api/rest/projects/c07dbc32-c2f9-4189-8ae2-3375f6aa1702/team/users?fields=name,id' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
--data-raw '{"id":"e6446bd8-7fec-430e-bc62-54c4e7a231b6"}'

    In this sample request we specified also fields parameter that let us confirm the name of the user that we added to the team. We used it just for the demonstration sake.

    In response, server returned the following data:

    {
  "type": "user",
  "id": "e6446bd8-7fec-430e-bc62-54c4e7a231b6",
  "name": "Mad Max"
}