---
metadata:
  - name: generator
    content: Diplodoc Platform v5.47.3
alternate:
  - https://yandex.com.tr/support/tracker/en/api-ref/queues/manage-access.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/support/tracker/en/llms.txt

# Granting queue access rights

This request allows you to set up [queue access permissions](https://yandex.com.tr/support/tracker/en/manager/queue-access.md).

<div class="request_example method_patch yfm-clipboard">
    <p>PATCH</p>
    <pre><code>https://api.tracker.yandex.net/v3/queues/&lt;queue_ID>/permissions</code></pre>
    <button class="yfm-clipboard-button"><svg width="16" height="16" viewBox="0 0 24 24" class="yfm-clipboard-icon" data-animation="15">
    <path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path>
    <path stroke="currentColor" fill="transparent" strokewidth="1.5" d="M9.5 13l3 3l5 -5" visibility="hidden">
        <animate id="visibileAnimation-15" attributeName="visibility" from="hidden" to="visible" dur="0.2s" fill="freeze" begin=""></animate>
        <animate id="hideAnimation-15" attributeName="visibility" from="visible" to="hidden" dur="1s" begin="visibileAnimation-15.end+1" fill="freeze"></animate>
    </path>
</svg>
</button>
</div>

<!-- source: en/_assets/style/methods.md -->

<!-- endsource: en/_assets/style/methods.md -->

## Query format {#query}

Before making a request, [get permission to access the API](https://yandex.com.tr/support/tracker/en/api-ref/access.md).

To set up queue access permissions, use an HTTP `PATCH` request. In the request body, specify the parameters in JSON format.

```json
PATCH /v3/queues/<queue_ID>/permissions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
   "create": {
      "groups": [<group_1_ID>, <group_2_ID>]
   },
   "write": {
      "users": {
         "remove": ["<user_1_username>", "<user_2_ID>"]
      },
      "groups": {
         "add":[<group_1_ID>]
       },
      "roles": {
         "add":["author", "assignee"]
      }
   },
   "read": {
      "groups": {
         "add":[<group_3_ID>]
       },
      "roles": {
         "add":["follower"]
      }
   },
   "grant": {
      "users": {
         "remove": ["<user_4_account_ID>",  "<user_2_ID>"]
      },
   },

}
```

<!-- source: en/_includes/api/headings.md -->
{% cut "Headers" %}

* `Host`: address of the node that provides the API.

* <!-- source: en/_includes/api/authorization.md -->
  `Authorization`: Authorization token about these formats:

    - `OAuth <OAuth_token>`: For authorization using the OAuth 2.0 protocol. [Learn more](https://yandex.com.tr/support/tracker/en/api-ref/access.md#about_OAuth)

    - `Bearer <IAM_token>`: For authorization using an IAM token, if a Yandex Cloud Organization organization is linked to Tracker. [Learn more](https://yandex.com.tr/support/tracker/en/api-ref/access.md#iam-token)
  <!-- endsource: en/_includes/api/authorization.md -->


* <!-- source: en/_includes/api/org-id.md -->
  `X-Org-ID` or `X-Cloud-Org-ID`: Organization ID.

  - Use the `X-Org-ID` header if a Tracker organization is linked to Yandex 360 for Business.

  - Use the `X-Cloud-Org-ID` header if a Tracker organization is linked to Yandex Cloud Organization.

  To get the organization ID, go to **Administration** → [**Organizations**](https://tracker.yandex.com/admin/orgs) and copy the value from the **ID** field. {#find-id}
  <!-- endsource: en/_includes/api/org-id.md -->


{% endcut %}
<!-- endsource: en/_includes/api/headings.md -->

{% cut "Resource" %}

| Parameter | Description | Data type |
-------- | -------- | ----------
| \<queue_ID\> | Queue ID or key. The queue key is case-sensitive. | String |

{% endcut %}

{% cut "Request body parameters" %}

The request body contains information required for access management.

**Acceptable request body object fields**

Specify at least one of the following fields in your request:

| Parameter | Description | Data type |
-------- | -------- | ----------
| create | Permissions to create issues in a queue | Map item |
| write | Permissions to edit issues in a queue | Map item |
| read | Permissions to read issues in a queue | Map item |
| grant | Permissions to update queue settings | Map item |


**Acceptable object fields that permissions apply to**

Each of the request body fields contains a list of users, groups, and roles that the respective permission action applies to. Specify at least one of the following fields in the list:

| Parameter | Description | Data type |
-------- | -------- | ----------
| users | User list | Object or array of elements |
| groups | Group list | Object or array of elements |
| roles | Role list | Object or array of elements |

**Acceptable object field values that permissions apply to**

In each field, you can specify either an array of IDs or an object:

- If an array of IDs is set, permissions for the specified resources will be created or overridden as requested.
- If an object is set, permissions will be added or revoked based on the specified key:

| Key | Description | Data type |
-------- | -------- | ----------
| add | Add a permission | Array of elements |
| remove | Revoke a permission | Array of elements |

**Acceptable IDs**

#|
|| Resource type | ID | Description |Data type ||
|| **users** | login | Username. | String ||
|| | uid | Unique ID of the user account in Tracker. | Number ||
|| | passportUid | Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID. | Number ||
||   | cloudUid | Unique user ID in Yandex Cloud Organization. | String ||
|| | trackerUid | Unique ID of the user account in Tracker. | Number ||
|| **groups** | id | Group ID.

You can get group IDs using the `https://api.tracker.yandex.net/v3/groups` request. | Number ||
|| **roles** | role_id | Role ID:
* `author`: Author
* `assignee`: Assignee
* `follower`: Follower
* `access`: With the right of access
 | String ||
|#


{% endcut %}

> Example 1: Grant permissions to create and edit issues in a queue with the `TESTQUEUE` key to the user named `user1`.
>
> - The HTTP `PATCH` method is used.
> - The permissions are granted to `user1` in the `TESTQUEUE`.
> - As a result of the request, the user's current queue permissions will be overridden.
> ```json
> PATCH /v3/queues/TESTQUEUE/permissions HTTP/1.1
> Host: api.tracker.yandex.net
> Authorization: OAuth <OAuth token>
> X-Org-ID or X-Cloud-Org-ID: <organization_ID>
>
> {
>     "create": {
>        "users": ["user1"]
>     },
>     "write": {
>     "users": ["user1"]
>     }
> }
> ```

> Example 2: Grant permission to set up a queue with the `TESTQUEUE` key to `user1` and revoke the same permission from the user whose unique ID is `12********`.
>
> - The HTTP `PATCH` method is used.
> - The `TESTQUEUE` setup permission is granted to `user1`.
> - The `TESTQUEUE` setup permission is revoked from the user with the `12********` ID.
> ```json
> PATCH /v3/queues/TESTQUEUE/permissions HTTP/1.1
> Host: api.tracker.yandex.net
> Authorization: OAuth <OAuth_token>
> X-Org-ID or X-Cloud-Org-ID: <organization_ID>
>
> {
>     "grant": {
>        "users": {
>           "add":["user1"],
>           "remove":['12********']
>        }
>     }
> }
> ```


## Response format {#answer}

{% list tabs %}
- Request executed successfully
   <!-- source: en/_includes/api/answer-200.md -->
   If the request is successful, the API returns a response with code `200 OK`.
   <!-- endsource: en/_includes/api/answer-200.md -->
   ```json
   {
       "self": "https://api.tracker.yandex.net/v3/queues/TESTQUEUE/permissions",
       "version": 11,
       "create": {
           "self": "https://api.tracker.yandex.net/v3/queues/TESTQUEUE/permissions/create",
           "users": [
                { "self": "https://api.tracker.yandex.net/v3/users/98********", "id": "98********", "display": "User 1", "cloudUid": "ajej6h7nffmtaf*****", "passportUid": 98******** }
           ],
           "roles": [
               { "self": "https://api.tracker.yandex.net/v3/roles/author", "id": "author", "display": "Author" },
               { "self": "https://api.tracker.yandex.net/v3/roles/queue-lead", "id": "queue-lead", "display": "Queue owner" },
               { "self": "https://api.tracker.yandex.net/v3/roles/assignee", "id": "assignee", "display": "Assignee" }
           ]
       },
       "write": {
           "self": "https://api.tracker.yandex.net/v3/queues/TESTQUEUE/permissions/write",
           "users": [
                { "self": "https://api.tracker.yandex.net/v3/users/98********", "id": "98********", "display": "User 1", "cloudUid": "ajej6h7nffmtaf*****", "passportUid": 98******** }
           ],
           "roles": [
               { "self": "https://api.tracker.yandex.net/v3/roles/author", "id": "author", "display": "Author" },
               { "self": "https://api.tracker.yandex.net/v3/roles/queue-lead", "id": "queue-lead", "display": "Queue owner" },
               { "self": "https://api.tracker.yandex.net/v3/roles/assignee", "id": "assignee", "display": "Assignee" }
           ]
       },
       "grant": {
           "self": "https://api.tracker.yandex.net/v3/queues/TESTQUEUE/permissions/grant",
           "users": [
                { "self": "https://api.tracker.yandex.net/v3/users/98********", "id": "98********", "display": "User 1", "cloudUid": "ajej6h7nffmtaf*****", "passportUid": 98******** }
           ],
           "roles": [
               { "self": "https://api.tracker.yandex.net/v3/roles/author", "id": "author", "display": "Author" },
               { "self": "https://api.tracker.yandex.net/v3/roles/queue-lead", "id": "queue-lead", "display": "Queue owner" },
               { "self": "https://api.tracker.yandex.net/v3/roles/assignee", "id": "assignee", "display": "Assignee" }
           ]
       }
   }

   ```

   {% cut "Response parameters" %}
   Parameter | Description | Data type
   ----- | ----- | -----
   self | Link to the object with granted queue access permissions | String
   version | Version number | Number
   create | Permissions to create issues in a queue | Object
   write | Permissions to edit issues in a queue | Object
   read | Permissions to read issues in a queue | Object
   grant | Permissions to update queue settings | Object

   {% endcut %}

- Request failed

   If the request is processed incorrectly, the API returns a response with an error code:

   <!-- source: en/_includes/api/answer-error-404.md -->
   404
   :   The requested object was not found. You may have specified an invalid object ID or key.
   <!-- endsource: en/_includes/api/answer-error-404.md -->

{% endlist %}