Privilege and Privilege Set API

This article describes API calls available for Privilege and Privilege Set configuration:

  • /api/privilege: Retrieve Privileges.
  • /api/privilege_set: Retrieve, create, update, and delete Privilege Sets.
  • /api/privilege_set_privilege: Retrieve, assign, and remove Privileges from Privilege Sets.

Prerequisites:

Table of contents :

  1. Access Admin > System > API Toolkit
  2. Retrieve Privileges
  3. Configure Privilege Sets
    1. Retrieve Privilege Sets
    2. Create Privilege Set
    3. Update Privilege Set
    4. Delete Privilege Set
  4. Configure Privilege Set Privileges
    1. Retrieve Privileges Assigned to Privilege Sets
    2. Assign Privilege to Privilege Set
    3. Remove Privilege from Privilege Set

1. Access Admin > System > API Toolkit

2. Retrieve Privileges

  • GET request to /api/privilege returns all Privileges.
  • GET request to /api/privilege/id/<ID> returns a single Privilege by its ID.
  1. Item: privilege
  2. Method: GET
  3. Optionally, apply filtering:
    • ID: Retrieve a single Privilege by ID.
    • class: Retrieve Privileges from a class.
    • for_power_users_only: Retrieve Privileges that can be assigned only to Power Users.
    • power_user_can_assign: Retrieve Privileges that can be assigned by Power Users.
  4. Enter an API Token.
  5. [Run request]

Example Response 

{
  "privileges": [
    {
      "id": 2,
      "name": "Add Annotation",
      "description": "Add explanatory text to data points on Metric or Report Charts",
      "class": "Collaboration",
      "for_power_user_only": "N",
      "power_user_can_assign": "Y",
      "required_privilege": null
    },
    {
      "id": 6,
      "name": "Set Homepage Refresh Frequency",
      "description": "Modify the refresh frequency of the Homepage in milliseconds",
      "class": "Personal Settings",
      "for_power_user_only": "N",
      "power_user_can_assign": "Y",
      "required_privilege": "12"
    }
  ]
}

Fields Description

Parameter NameValue TypeDescription
privilegearrayAn array with Privilege data.
idintegerPrivilege ID.
namestringPrivilege name.
descriptionstringWhat this Privilege allows the Users to do.
classstringName of the Privilege class this Privilege belongs to.
for_power_user_onlystringWhether the Privilege can only be held by Power Users.

  • «Y»: Privilege can be granted only to Power Users.
  • «N»: Privilege can be granted to Power Users and Regular Users.
power_user_can_assignstringWhether Power-User admins may grant this Privilege.
  • «Y»: Power Users can grant this Privilege.
  • «N»: Only Admins can grant this Privilege.
required_privilegestringComma-separated IDs of prerequisite Privileges that the recipient must already hold before this Privilege can be assigned.
  • An empty or null value means no prerequisite Privileges are required.

3. Configure Privilege Sets

3.1. Retrieve Privilege Sets

  • GET request to /api/privilege_set returns all Privilege Sets.
  • GET request to /api/privilege_set/id/<ID> returns a single Privilege Set by its ID.
  1. Item: privilege_set
  2. Method: GET
  3. Optionally, apply filtering:
    • ID: Retrieve a single Privilege Set by ID.
  4. Enter an API Token.
  5. [Run request]

Example Response 

{
  "privilege_sets": [
    {
      "id": 1,
      "name": "Regular User"
    },
    {
      "id": 2,
      "name": "Power User"
    },
    {
      "id": 3,
      "name": "Demo Privilege Set"
    },
    {
      "id": 5,
      "name": "Distributor's Privilege Set"
    }
  ]
}

Fields Description

Parameter NameValue TypeDescription
privilege_setsarrayAn array with Privilege Set data.
idintegerPrivilege Set ID.
namestringPrivilege Set name.

3.2. Create Privilege Set

  • POST request to /api/privilege_set with body {"name": "<Privilege_Set_name>"} creates a new Privilege Set.
  1. Item: privilege_set
  2. Method: POST
  3. Enter the ID of an existing Privilege Set.
  4. Select JSON request and provide a name for the new Privilege Set.
  5. Enter an API Token.
  6. [Run request]

3.3. Update Privilege Set

  • PUT request to /api/privilege_set/id/<ID> with body {"name": "<Privilege_Set_New_Name>"} updates the Privilege Set name.
  1. Item: privilege_set
  2. Method: PUT
  3. Enter the ID of the Privilege Set you want to modify.
  4. Select JSON request and provide a new name for the Privilege Set.
  5. Enter an API Token.
  6. [Run request]

3.4. Delete Privilege Set

  • DELETE request to /api/privilege_set/id/<ID> deletes the specified Privilege Set.
  1. Item: privilege_set
  2. Method: DELETE
  3. Enter the ID of the Privilege Set you want to delete.
  4. Enter an API Token.
  5. [Run request]

4. Configure Privilege Set Privileges

4.1. Retrieve Privileges Assigned to Privilege Sets

  • GET request to /api/privilege_set_privilege returns all Privilege-to-Privilege Set mappings.
  • GET request to /api/privilege_set_privilege/id/<ID> returns a single Privilege-to-Privilege Set mapping by its ID.
  1. Item: privilege_set_privilege
  2. Method: GET
  3. Optionally, apply filtering:
    • ID: Retrieve a single Privilege-to-Privilege Set mapping by ID.
  4. Enter an API Token.
  5. [Run request]

Example Response

Example for GET /api/privilege_set_privilege:

{
  "privilege_set_privileges": [
    {
      "id": 1,
      "privilege_set_id": 1,
      "privilege_id": 2
    },
    {
      "id": 13,
      "privilege_set_id": 1,
      "privilege_id": 6
    }
  ]
}

Example for GET /api/privilege_set_privilege/id/<ID>:

{
  "privilege_set_privilege": {
    "id": 1,
    "privilege_set_id": 1,
    "privilege_id": 2
  }
}

Fields Description

Parameter NameValue TypeDescription
privilege_set_privilegesarrayAn array with all Privilege-to-Privilege Set mappings.
idintegerPrivilege-to-Privilege Set mapping ID.
privilege_set_id
integerID of the Privilege Set to which the Privilege is assigned
privilege_id
integerID of the Privilege assigned to the Privilege Set.

4.2. Assign Privilege to Privilege Set

  • POST request to /api/privilege_set_privilege with body {"privilege_set_id": "<ID>", "privilege_id": "<ID>"} assigns a Privilege to a Privilege Set.
  1. Item: privilege_set_privilege
  2. Method: POST
  3. Enter the ID of an existing Privilege-to-Privilege Set mapping.
  4. Select JSON request and enter the following values:
    • privilege_set_id: ID of the Privilege Set to which you want to assign a Privilege.
    • privilege_id: ID of the Privilege that you want to assign to the Privilege Set.
  5. Enter an API Token.
  6. [Run request]

4.3. Remove Privilege from Privilege Set

  • DELETE request to /api/privilege_set_privilege/id/<ID> removes a Privilege from a Privilege Set.
  1. Item: privilege_set_privilege
  2. Method: DELETE
  3. Enter the ID of the Privilege-to-Privilege Set mapping you want to remove.
  4. Enter an API Token.
  5. [Run request]