# Access Management Query Syntax

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/youtrack/devportal/llms.txt).

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](resource-api-assignedRoles.html) | `scope:`, `holder:`, `role:`, and `permission:`. |
| [GET /api/roles](resource-api-roles.html) | `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](api-users-yt-vs-hub.html#structured-user-searches).

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](api-concept-pagination.html).

## 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](api-users-yt-vs-hub.html).

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](resource-api-permissions.html).

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.

> **Note:**
> `!` is an exact-match suffix, not a negation operator. To negate a condition, put `not` before it, for example, `not scope:global`.

| 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
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
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
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.