Access Management Query Syntax

Use the query parameter to filter role assignments and find roles with specific permissions. Role and role assignment queries use their own search syntax.

Endpoints

Endpoint	Filters covered on this page
`GET /api/assignedRoles`	`scope:`, `holder:`, `role:`, and `permission:`.
`GET /api/roles`	`permission:` to find roles that include a permission.

Search fields are specific to each resource. The assignment filters described below apply to /api/assignedRoles. For user and group searches, see Search Users by Email or Group Membership.

The query parameter is optional. If you omit it or pass an empty value or only whitespace, the resource applies no search filter. The response is subject to the resource's permissions and pagination limits.

Search Fields

Write each condition as field:value. Use YouTrack database IDs for projects, organizations, users, groups, and roles. For details about IDs, see Users, Groups, and Access Management.

All IDs in the examples are sample database IDs. Replace them with database IDs from your YouTrack instance.

Field	Accepted value	Matches
`scope:`	The database ID of a project or organization, or `global`.	Assignments that apply in the specified scope, including assignments inherited from broader scopes.
`holder:`	The database ID of a user or user group.	Assignments to the holder, including assignments inherited through group or project team membership.
`role:`	The database ID of a role.	Assignments of the specified role.
`permission:`	A permission key, for example, `JetBrains.YouTrack.READ_ISSUE`.	Assignments whose role includes the specified permission.

To find permission keys, request GET /api/permissions?fields=id,name. Use the permission's id value as the key. See Permissions.

Unknown search fields and unknown permission keys cause a 400 Bad Request response.

Direct and Inherited Assignments

Scope and holder filters include inherited assignments by default. Append ! to a scope or holder value to return only direct role assignments.

Query	Matches
`scope:0-0`	Assignments in project `0-0`, its organization, and the global scope.
`scope:0-0!`	Assignments directly in project `0-0`.
`scope:global`	Assignments in the global scope.
`holder:24-2`	Assignments to user `24-2` and to groups or project teams through which the user inherits roles.
`holder:24-2!`	Assignments directly to user `24-2`.

For an organization ID, scope: includes the organization and the global scope. With !, the query matches only assignments in that organization.

For a user group ID, holder: also matches assignments to groups and project teams through which the group inherits roles. With !, the query matches only assignments directly to that group.

For example, assume your account can read two assignments in project 0-0, one in its organization, and one globally. The query scope:0-0 matches all four assignments. The query scope:0-0! matches only the two project assignments. The number of matches depends on your instance's assignments and your permissions.

Combine Conditions

Syntax	Meaning	Example
Adjacent field conditions or `&&`	Match both conditions.	`scope:0-0! holder:24-2!`
`\|\|`	Match either condition.	`scope:0-0! \|\| scope:0-1!`
`not`	Exclude matches for the following condition.	`not scope:global`
`( )`	Group conditions.	`(scope:0-0! \|\| scope:0-1!) && holder:24-2!`
Comma-separated values	Match any listed value. An optional `+` before the colon makes this explicit.	`role:42-1,42-2` or `role+:42-1,42-2`
`&` before the colon	Match all listed values.	`permission&:JetBrains.YouTrack.READ_ISSUE,JetBrains.YouTrack.CREATE_ISSUE`

Use parentheses to make grouping explicit when you combine operators. Apply ! to each value that requires an exact match, for example, scope:0-0!,0-1!.

URL-encode the query value. In cURL, use --data-urlencode with --get to encode spaces, ampersands, and other special characters.

Request Examples

Find Direct Project Assignments

When migrating a Hub /users/{id}/projectroles request, use the YouTrack user and project database IDs. Apply ! to both values to retrieve roles assigned directly to the user in that project.

        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),scope(id)' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer <permanent_token>'
      

Replace 0-0 with the project's database ID and 24-2 with the user's database ID. To retrieve direct project assignments for every holder, use only scope:0-0!.

Include Inherited Assignments

To include assignments inherited by a user in a project, omit both exact-match suffixes:

        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),scope(id)' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer <permanent_token>'
      

This query includes assignments at the project, organization, and global scopes. It also includes assignments to groups and project teams through which the user inherits roles.

Find Roles with a Permission

To find roles that include the Read Issue permission, query /api/roles with its permission key:

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

To find assignments of roles with this permission, use the same permission: condition with /api/assignedRoles. Add scope: and holder: conditions to limit the assignments.

02 November 2026