llms.txt: machine-readable documentation index. Markdown version of this page is also available.

YouTrack Developer Portal Help

Assigned Roles

This resource lets you work with roles assigned to a user or a group in YouTrack.

Available since YouTrack 2026.1.

Resource

/api/assignedRoles

Returned entity

AssignedRole. For the description of the entity attributes, see Supported Fields section.

Supported methods

AssignedRole attributes

Represents a role assigned to a user or a group in a specific scope.

Available since YouTrack 2026.1.

Attributes

This table describes attributes of the AssignedRole 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 database ID of the assigned role. Read-only.

role

Role

The role that is assigned.

scope

AccessScope

The scope where the role is assigned. Possible values: Global, Organization, or Project.

holder

The user or group that holds the role. Set this attribute when creating an assignment. Read-only.

Read a List of AssignedRoles

Get all roles assigned to a user or a group.

Use query to filter assignments by scope, holder, role, or permission.

Required permissions

For global roles, requires Low-level Admin Read permission.

For organization roles, requires Update Organization permission.

For project roles, requires Update Project permission.

Request syntax

GET /api/assignedRoles?{fields}&{$top}&{$skip}&{query}

null

The database ID of AssignedRole

Request parameters

Parameter

Type

Description

fields

String

A list of AssignedRole attributes that should be returned in the response. If no field is specified, only the entityID is returned.

$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 entries that are returned in the response. If you don't set the $top value, the server limits the maximum number of returned entries.

The server returns a maximum of 42 entries for most resources that return collections. For more information, see Pagination.

query

String

Filter role assignments by the following fields:

  • scope: accepts the database ID of a YouTrack project or organization, or global.

  • holder: accepts the database ID of a YouTrack user or user group.

  • role: accepts the database ID of a YouTrack role.

  • permission: accepts a permission key.

Scope and holder filters include inherited assignments by default. To match only the specified scope or holder, append ! to that value.

For example, scope:0-0! holder:24-2! matches roles assigned directly to user 24-2 in project 0-0. Replace the example IDs with database IDs from your YouTrack instance.

! is an exact-match suffix. To negate a condition, use not.

This parameter is optional. If you omit it or pass an empty value or only whitespace, the resource applies no search filter.

For operators and examples, see Access Management Query Syntax.

Sample 1

Find assignments for user 24-2, including assignments inherited through groups and project teams. Replace sample database IDs with IDs from your instance.

Sample request

curl --get https://example.youtrack.cloud/api/assignedRoles \ --data-urlencode query=holder:24-2 \ --data-urlencode 'fields=id,role(id,name,description),holder(id,login,$type),scope(id,$type)' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <permanent_token>'

Sample response body

[ { "role": { "description": "Read issues in assigned scopes.", "name": "Issue Reader", "id": "28-33" }, "scope": { "id": "549-0", "$type": "ProjectScope" }, "holder": { "login": "john.smith", "id": "24-2", "$type": "User" }, "id": "31-70" }, { "role": { "description": "Read issues in assigned scopes.", "name": "Issue Reader", "id": "28-33" }, "scope": { "id": "544-0", "$type": "GlobalScope" }, "holder": { "login": "john.smith", "id": "24-2", "$type": "User" }, "id": "31-72" }, { "role": { "description": "Read issues in assigned scopes.", "name": "Issue Reader", "id": "28-33" }, "scope": { "id": "550-0", "$type": "OrganizationScope" }, "holder": { "login": "john.smith", "id": "24-2", "$type": "User" }, "id": "31-74" }, { "role": { "description": "Read issues in assigned scopes.", "name": "Issue Reader", "id": "28-33" }, "scope": { "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "23-2", "$type": "NestedGroup" }, "id": "31-71" }, { "role": { "description": "The Contributor role is intended for users who create and work with issues. Contributors can create new issues, add comments, view existing issues and comments, and update most issue attributes.", "name": "Contributor", "id": "28-2" }, "scope": { "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "574-0", "$type": "ProjectTeam" }, "id": "31-75" }, { "role": { "description": "Read issues in assigned scopes.", "name": "Issue Reader", "id": "28-33" }, "scope": { "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "574-0", "$type": "ProjectTeam" }, "id": "31-73" } ]

Sample 2

Find roles assigned directly to user 24-2 in project 0-0.

Sample request

curl --get https://example.youtrack.cloud/api/assignedRoles \ --data-urlencode 'query=scope:0-0! holder:24-2!' \ --data-urlencode 'fields=id,role(id,name),holder(id,$type),scope(id,project(id),$type)' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <permanent_token>'

Sample response body

[ { "role": { "name": "Issue Reader", "id": "28-33" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "24-2", "$type": "User" }, "id": "31-70" } ]

Sample 3

Find assignments in project 0-0 whose roles include the Read Issue permission.

Sample request

curl --get https://example.youtrack.cloud/api/assignedRoles \ --data-urlencode 'query=scope:0-0! permission:JetBrains.YouTrack.READ_ISSUE' \ --data-urlencode 'fields=id,role(id,name),holder(id,$type),scope(id,project(id),$type)' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <permanent_token>'

Sample response body

[ { "role": { "name": "Contributor", "id": "28-2" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "574-0", "$type": "ProjectTeam" }, "id": "31-75" }, { "role": { "name": "Project Admin", "id": "28-3" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "24-0", "$type": "User" }, "id": "31-76" }, { "role": { "name": "Issue Reader", "id": "28-33" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "24-2", "$type": "User" }, "id": "31-70" }, { "role": { "name": "Issue Reader", "id": "28-33" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "23-2", "$type": "NestedGroup" }, "id": "31-71" }, { "role": { "name": "Issue Reader", "id": "28-33" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "574-0", "$type": "ProjectTeam" }, "id": "31-73" } ]

Assign a Role to a User or a Group

Assign a role to a user or a group.

Required permissions

For global roles, requires Low-level Admin Write permission.

For organization roles, requires Update Organization permission.

For project roles, requires Update Project permission.

Request syntax

POST /api/assignedRoles?{fields}

null

The database ID of AssignedRole

Request parameters

Parameter

Type

Description

fields

String

A list of AssignedRole attributes that should be returned in the response. If no field is specified, only the entityID is returned.

Sample 1

Assign the Issue Reader role to user 24-2 in project 0-0.

Sample request

curl --request POST 'https://example.youtrack.cloud/api/assignedRoles?fields=id,role(id,name),holder(id,$type),scope(id,project(id),$type)' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <permanent_token>' \ --header 'Content-Type: application/json' \ --data '{ "scope": { "project": { "id": "0-0" }, "$type": "ProjectScope" }, "holder": { "id": "24-2", "$type": "User" }, "role": { "id": "28-33" }, "$type": "AssignedRole" }'

Sample request body

{ "scope": { "project": { "id": "0-0" }, "$type": "ProjectScope" }, "holder": { "id": "24-2", "$type": "User" }, "role": { "id": "28-33" }, "$type": "AssignedRole" }

Sample response body

{ "role": { "name": "Issue Reader", "id": "28-33" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "24-2", "$type": "User" }, "id": "31-70" }

Sample 2

Assign the Issue Reader role to user group 23-2 in project 0-0.

Sample request

curl --request POST 'https://example.youtrack.cloud/api/assignedRoles?fields=id,role(id,name),holder(id,$type),scope(id,project(id),$type)' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <permanent_token>' \ --header 'Content-Type: application/json' \ --data '{ "scope": { "project": { "id": "0-0" }, "$type": "ProjectScope" }, "holder": { "id": "23-2", "$type": "NestedGroup" }, "role": { "id": "28-33" }, "$type": "AssignedRole" }'

Sample request body

{ "scope": { "project": { "id": "0-0" }, "$type": "ProjectScope" }, "holder": { "id": "23-2", "$type": "NestedGroup" }, "role": { "id": "28-33" }, "$type": "AssignedRole" }

Sample response body

{ "role": { "name": "Issue Reader", "id": "28-33" }, "scope": { "project": { "id": "0-0" }, "id": "549-0", "$type": "ProjectScope" }, "holder": { "id": "23-2", "$type": "NestedGroup" }, "id": "31-71" }
02 November 2026
Operations with Specific TagOperations with Specific AssignedRole