Get entity access settings

Use this request to grant or revoke access to an entity: goal, project, or project portfolio. Learn more about access settings in How to configure access rights in projects, portfolios, and goals.

PATCH

https://api.tracker.yandex.net/v3/entities/<entity_type>/<entity_ID>/extendedPermissions

You can also configure permissions for an entity using this request:

PATCH https://api.tracker.yandex.net/v3/entities/<entity_type>/<entity_ID>/permissions

In this request, you can't define permissionSources, which is a parameter that specifies the parent entity from which the current entity inherits access settings. The format of the request and response body matches the acl object format. See the description for details.

Query format

Before making a request, get permission to access the API.

To update an entity, use an HTTP PATCH request. In the request body, specify the parameters in JSON format.

PATCH /v3/entities/<entity_type>/<entity_ID>/extendedPermissions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
    "permissionSources": [],
    "acl": {
        "grant": {
            "READ": {
                "users": ["username1", "username2"],
                "groups": [],
                "roles": []
            },
            "WRITE": {
                "users": [],
                "groups": [1, 2],
                "roles": []
            },
            "GRANT": {
                "users": [],
                "groups": [],
                "roles": []
            }
        },
        "revoke": {
            "READ": {
                "users": {"uid": 123********},
                "groups": 3,
                "roles": []
            },
            "WRITE": {
                "users": [],
                "groups": [],
                "roles": "FOLLOWER"
            },
            "GRANT": {
                "users": [],
                "groups": [],
                "roles": []
            }
        }
    }
}
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

    • Bearer <IAM_token>: For authorization using an IAM token, if a Yandex Cloud Organization organization is linked to Tracker. Learn more

  • 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 and copy the value from the ID field.

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. You can use the id or shortId parameter as the ID. String
Request body parameters

Additional parameters

Parameter

Description

Data type

permissionSources

The ID of the parent entity from which the current entity inherits access settings.

  • To enable access inheritance, specify the ID of the main portfolio (for portfolios or projects) or the parent goal (for goals).
    You'll find the ID of the parent entity in the response to the Get entity access settings request.
    To change the parent entity, use the Updating an entity request.
  • To disable access inheritance, pass "permissionSources": []

String or array of strings

acl

Object that specifies the permissions that you want to grant or revoke

Object

If permissionSources is set to a non-empty value:

To update permissions, first disable access inheritance from the parent entity.

acl object fields

Parameter Description Data type
grant Object that specifies the permissions you want to grant to users, groups, or roles revoke
object Object that specifies the permissions you want to revoke from users, groups, or roles Object

grant and revoke object fields

Parameter Description Data type
READ Object with details about users, groups, or roles for whom you want to grant or revoke view access to the entity GRANT
object Object with details about users, groups, or roles for whom you want to grant or revoke access to the entity WRITE
object Object with details about users, groups, or roles for whom you want to grant or revoke edit access to the entity Object

READ, GRANT, and WRITE object fields

Parameter

Description

Data type

users

User IDs or usernames for whom you want to grant or revoke this type of access

String or array of strings

groups

Group IDs for whom you want to grant or revoke this type of access

Number or array of numbers

roles

List of entity roles for which you want to grant or revoke this type of access:

  • AUTHOR: Author.
  • OWNER: Lead.
  • CLIENT: Customer.
  • FOLLOWER: Follower.
  • MEMBER: Participants

String or array of strings

Example 1: Enable access inheritance for a project from the main portfolio.

PATCH /v3/entities/project/655f8cc52*****/extendedPermissions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
   "permissionSources": "67ffd7e3********"
}

Example 2: Disable access inheritance for a project from the main portfolio and grant edit access to group with ID 2.

PATCH /v3/entities/project/655f8cc52*****/extendedPermissions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
   "permissionSources": [],
   "acl": {
       "grant": {
           "WRITE": {
               "users": [],
               "groups": 2,
               "roles": []
           }
       }
   }
}

Example 3: Grant read-only access to a project for the user with username1. You need to disable access inheritance from the main portfolio first.

PATCH /v3/entities/project/655f8cc52*****/extendedPermissions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
  "acl": {
      "grant": {
          "READ": {
              "users": {"login": "username1"}
          }
      }
  }
}

Example 4: Revoke access for managing permissions for the project from the user with username2 using the https://api.tracker.yandex.net/v3/entities/<entity_type>/<entity_id>/permissions method. You need to disable access inheritance from the main portfolio first.

PATCH /v3/entities/project/655f8cc52*****/permissions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
  "revoke": {
      "GRANT": {
          "users": "username2"
      }
    }
}

Response format

If the request is successful, the API returns a response with code 200 OK.

The response body contains information about the entity's access settings in JSON format.

{
    "acl": {
        "READ": {
            "users": [
                {
                    "self": "https://api.tracker.yandex.net/v3/users/11********",
                    "id": "11********",
                    "display": "User Name",
                    "passportUid": 11********
                }
            ],
            "groups": [
                {
                    "self": "https://api.tracker.yandex.net/v3/groups/1",
                    "id": "1",
                    "display": "Group 1"
                }
            ],
            "roles": []
        },
        "GRANT": {
            "users": [],
            "groups": [
                {
                    "self": "https://api.tracker.yandex.net/v3/groups/2",
                    "id": "2",
                    "display": "Group 2"
                }
            ],
            "roles": [
                "AUTHOR",
                "OWNER"
            ]
        },
        "WRITE": {
            "users": [],
            "groups": [
                {
                    "self": "https://api.tracker.yandex.net/v3/groups/3",
                    "id": "3",
                    "display": "Group 3"
                }
            ],
            "roles": [
                "CLIENT",
                "AUTHOR",
                "FOLLOWER",
                "OWNER",
                "MEMBER"
            ]
        }
    },
    "permissionSources": [
        {
            "self": "https://api.tracker.yandex.net/v3/entities/portfolio/67ffd7e3********",
            "id": "67ffd7e3********",
            "display": "My portfolio"
        }
    ],
    "parentEntities": {
        "primary": {
            "self": "https://api.tracker.yandex.net/v3/entities/portfolio/67ffd7e3********",
            "id": "67ffd7e3********",
            "display": "My portfolio"
        },
        "secondary": []
    }
}
Response parameters
Parameter Description Data type
acl An object detailing the users, groups, and roles with various access types for the entity Object
permissionSources The parent entity (the main portfolio or parent goal) from which the current entity inherits its access permissions Object
parentEntities A list of parent entities from which the current entity inherits access permissions Object

parentEntities object fields

Parameter Description Data type
primary The main portfolio (for projects and portfolios) or parent goal (for goals) Object
secondary For projects and portfolios: a list of additional portfolios
For goals, the parameter value is always empty		 Array of objects

If the request address specifies the API v2, the parentEntity object contains information only about the main portfolio or parent goal.

Fields of the object that contains entity data

The permissionSources, primary, and secondary parameters contain objects with the following fields:

Parameter Description Data type
self Address of the API resource with information about the entity String
id Entity ID String
display Entity name String

acl object fields

Parameter Description Data type
READ An object detailing the users, groups, and roles with view access to the entity Object
GRANT An object detailing the users, groups, and roles that can manage access settings for the entity Object
WRITE An object detailing the users, groups, and roles with edit access to the entity Object

READ, GRANT, and WRITE object fields

Parameter

Description

Data type

users

A list of users with this access type

Object array

groups

A list of groups with this access type

Object array

roles

A list of entity roles with this access type:

  • AUTHOR: Author.
  • OWNER: Lead.
  • CLIENT: Customer.
  • FOLLOWER: Follower.
  • MEMBER — Participants.

String array

Fields of objects in the users array

Parameter Description Data type
self Address of the API resource with information about the user String
id User ID. String
display Displayed user name String
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

Fields of objects in the groups array

Parameter Description Data type
self The address of the API resource that contains information about the user group String
id Group ID String
display Group display name String

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 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.
412
A conflict occurred while editing the object. The error may be due to an invalid update version.
423
Object edits disabled. The version parameter value limit (the maximum number of object updates) might have been exceeded. The maximum version value is 10100 for robots and 11100 for users.
428
Access to the resource is denied. Make sure all required conditions for the request are specified.
Previous
Get access settings
Next
Creating a project