Get entity access settings

Use this request to get information about access settings for entities: goals, projects, or project portfolios. Learn more about access settings in How to configure access rights in projects, portfolios, and goals.

GET

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

You can also use this request to retrieve permissions for an entity:

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

Unlike other requests, this one doesn't return permissionSources, which is a parameter that specifies the parent entity from which the current entity inherits access settings. The response format matches the acl object format. See the description for details.

Query format

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

To get an entity's access settings, use an HTTP GET request.

GET /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>
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 AdministrationOrganizations 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

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.
404
The requested object was not found. You may have specified an invalid object ID or key.