Element Access API (v7.1.2+)

This article describes the API calls that return all Users and Groups with access to a specified element:

Prerequisites:

NOTES:

  • Only Admin Users and Power Users with edit access to the element can execute these API calls.
  • See User Element and Group Element API for API calls on all elements available to Users and Groups.

Table of contents:

  1. Access Admin > System > API Toolkit
  2. Get Users and Groups with Element Access
  3. Get Comprehensive Access List

1. Access Admin > System > API Toolkit

2. Get Users and Groups with Element Access

  • The GET request to /api/element/access/id/<id> returns Users and Groups with access to the specified element.
  1. Item: element/access
  2. Method: GET
  3. ID: Enter ID of the element
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "element_access": {
    "direct_groups": [
      {
        "id": 53,
        "name": "Documentation Group",
        "can_edit": "N"
      }
    ],
    "category_groups": [
      {
        "id": 9,
        "name": "Manufacturing Group",
        "can_edit": "N"
      }
    ],
    "direct_users": [
      {
        "id": 88,
        "username": "Anna",
        "display_name": "Anna Kennedy",
        "is_owner": "Y",
        "can_edit": "Y"
      }
    ],
    "category_users": [
      {
        "id": 175,
        "username": "robregular",
        "first_name": null,
        "last_name": null,
        "can_edit": "N/A"
      }
    ],
    "all_users": [
      {
        "id": 193,
        "username": "[email protected]",
        "first_name": "John",
        "last_name": "Powers",
        "is_owner": "N",
        "can_edit": "N/A"
      },
      {
        "id": 175,
        "username": "robregular",
        "first_name": null,
        "last_name": null,
        "is_owner": "N",
        "can_edit": "N/A"
      }
    ]
  }
}

Fields Description

NOTE: The list of Users and Groups returned by the API corresponds to the lists from the Access & Ownership tab of the element editor in the UI.

Parameter Name
 Value Type Description
direct_groups
 array Groups with access to the element.
category_groups
 array Groups with category access to the element.
Below are the Group object parameters from the direct_groups and category_groups arrays:
id integer The ID of the Group.
name string The name of the Group.
can_edit string Whether or not the Power Users have edit access to the element. ("Y"/"N")

direct_users array Users with access to the element. 
category_users array Users with category access to the element.
all_users array All Users with element access.
Below are the User object parameters from the direct_users, category_users, and all_users arrays:
id integer User ID.
username string Username
first_name string
 User’s first name.
last_name string
 User’s last name.
can_edit string
 Whether or not the User has edit access to the element. ("Y"/"N")

3. Get Comprehensive Access List

  • The GET request to element/access/comprehensive?element=<id> returns a list of Users with comprehensive access to the element, grouped by each dimension value.
  1. Item: element/access/comprehensive
  2. Method: GET
  3. ID: Enter ID of the element
  4. Optionally, apply filtering:
    • dimension_value: The dimension value of the element.
    • user: The ID of the User.
    • with_admin: Set to "Y" to return all Admins who were not directly assigned access but still have access to the element.
  5. Enter an API Token
  6. [Run request]

Example Response 

{
  "element_access": [
    {
      "element_id": 152740,
      "dimension_value_id": 2772,
      "users": [
        66,
        156,
        157,
        158,
        202
      ]
    },
    {
      "element_id": 152740,
      "dimension_value_id": 2776,
      "users": [
        66,
        156,
        157,
        158,
        202
      ]
    }
  ]
}

Fields Description

Parameter Name Value Type Description
element_id integer The ID of the element.
dimension_value_id integer The ID of the dimension value.
users array An array with IDs of the Users with element access grouped by dimension values.