## Query format {#query}
Before making a request, [get permission to access the API](https://yandex.ru/support/tracker/en/api/access.md).
Pass the `grant` and `revoke` objects at the top level of the request body. The API adds or removes the specified permissions and preserves all other access settings.
```json translate=no
PATCH /v3/entities/{entity_type}/{entity_ID}/permissions
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID or X-Cloud-Org-ID: ORGANIZATION_ID
{
"grant": {
"READ": {
"users": "username1"
}
},
"revoke": {
"GRANT": {
"users": "username2"
}
}
}
```
{% cut "Headers" %}
* `Host`: address of the node that provides the API.
*
`Authorization`: Authorization token about these formats:
- `OAuth OAUTH_TOKEN`: For authorization using the OAuth 2.0 protocol. [Learn more](https://yandex.ru/support/tracker/en/api/access.md#about_OAuth)
- `Bearer IAM_TOKEN`: For authorization using an IAM token, if a Yandex Identity Hub organization is linked to Tracker. [Learn more](https://yandex.ru/support/tracker/en/api/access.md#iam-token)
*
# ID types {#types}
`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 Identity Hub.
# Finding the ID {#find-id}
To get the organization ID, go to **Administration** → [**Organizations**](https://tracker.yandex.com/admin/orgs) and copy the value from the **ID** field.
{% endcut %}
{% cut "Resource" %}
| Parameter | Description | Data type |
-------- | -------- | ----------
| `entity_type` | Entity type:
project
portfolio
goal
| String |
| `entity_ID` | Entity ID. To get the ID, see the [entity list](search-entities.md). You can use the `id` or `shortId` parameter as the ID. | String |
{% endcut %}
You can use the `id` or `shortId` value for the `{entity_ID}` parameter.
{% cut "Request body parameters" %}
| Parameter | Description | Data type |
| -------- | -------- | ---------- |
| [grant](#read-grant-write-request) | Permissions to grant | Object |
| [revoke](#read-grant-write-request) | Permissions to revoke | Object |
`grant` and `revoke` **object fields** {#read-grant-write-request}
| Parameter | Description | Data type |
| -------- | -------- | ---------- |
| [READ](#principals) | Users, groups, and roles to grant or revoke view access to the entity | Object |
| [GRANT](#principals) | Users, groups, and roles to grant or revoke access management permissions | Object |
| [WRITE](#principals) | Users, groups, and roles to grant or revoke edit access to the entity | Object |
`READ`, `GRANT`, and `WRITE` **object fields** {#principals}
#|
|| Parameter | Description | Data type ||
|| users | User IDs or usernames | String or array of strings ||
|| groups | Group IDs | Number or array of numbers ||
|| roles | Entity roles: `AUTHOR`, `OWNER`, `CLIENT`, `FOLLOWER`, `MEMBER` | String or array of strings ||
|#
{% endcut %}
{% note warning "" %}
Don't pass the `permissionSources` parameter in the request body: the API returns a `400` error. To update inherited permissions, use the [Change extended entity access settings](https://yandex.ru/support/tracker/en/api/entities/patch-access.md) request.
{% endnote %}
## Response format {#answer}
{% list tabs %}
- Request executed successfully
If the request is successful, the API returns a response with code `200 OK`.
The API returns an object with the resulting access permissions. The `READ`, `GRANT`, and `WRITE` properties are at the top level. The response doesn't include `acl`, `permissionSources`, or `parentEntities`.
```json translate=no
{
"READ": {
"users": [],
"groups": [],
"roles": []
},
"GRANT": {
"users": [],
"groups": [],
"roles": ["AUTHOR", "OWNER"]
},
"WRITE": {
"users": [],
"groups": [],
"roles": ["CLIENT", "AUTHOR", "FOLLOWER", "OWNER", "MEMBER"]
}
}
```
- Request failed
If the request is processed incorrectly, the API returns a response with an error code:
400
: One or more request parameters have an invalid value.
401
: The user is not authorized. Make sure that actions described in the [API access](https://yandex.ru/support/tracker/en/api/access.md) section are performed.
403
: You are not authorized to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.
404
: The requested object was not found. You may have specified an invalid object ID or key.
{% endlist %}