Dataset Access API (v7.2.0+)

This article describes the API endpoints used to view and manage the access that Users and Groups are granted to Datasets, including whether they can edit the Dataset, granted directly to a User or indirectly via Group membership:

  • /api/dataset/access: Returns the Groups and Users that have access to a Dataset, identifying which have edit access: directly or via Group membership.
  • /api/group_dataset: View, grant, and revoke a Group's access to Datasets (with optional edit access).
  • /api/user_dataset: View, grant, and revoke a User's access to Datasets (with optional edit access).

Prerequisites:

NOTES:

  • Only Admin Users and Power Users with edit access to the Dataset can execute these API calls.
  • See the Dataset API article for API calls on all Dataset-related objects.

Table of Contents

  1. Access Admin > System > API Toolkit
  2. Retrieve Users and Groups with Access to Dataset
  3. Configure Group_Dataset Associations
    1. Retrieve Groups With Access to Dataset
    2. Grant Group Access to Dataset
    3. Remove Group Access from Dataset
  4. Configure User_Dataset Associations
    1. Retrieve Users With Access to Dataset
    2. Grant User Access to Dataset
    3. Remove User Access from Dataset

1. Access Admin > System > API Toolkit

2. Retrieve Users and Groups with Access to Dataset

A GET request to /api/dataset/access/id/<id> returns the Groups and Users that have access to the specified Dataset. The response shows which Groups have access (and whether their members can edit), the Users with direct access, and all Users with access (directly or via Group), excluding Admins.

  1. Item: dataset/access
  2. Method: GET
  3. ID: Enter the ID of the Dataset.
  4. Enter an API Token.
  5. [Run request]

Example Response 

{
  "dataset_access": {
    "direct_groups": [
      {
        "id": 53,
        "name": "Documentation Group",
        "can_edit": "Y"
      }
    ],
    "direct_users": [
      {
        "id": 168,
        "username": "[email protected]",
        "display_name": "Test User",
        "can_edit": "N"
      }
    ],
    "all_users": [
      {
        "id": 193,
        "username": "[email protected]",
        "first_name": "John",
        "last_name": "Powers",
        "can_edit": "Y"
      }
    ]
  }
}

Fields Description

Parameter NameValue TypeDescription
dataset_access
objectContains the Groups and Users with access to the Dataset.
direct_groups
arrayGroups with access to the Dataset.
Below are the Group object parameters from the direct_groups array:
id
integerThe ID of the Group.
name
stringThe name of the Group.
can_edit
stringWhether the Group's members can edit the Dataset. ("Y"/"N")
direct_users
arrayUsers with direct access to the Dataset.
all_users
arrayAll Users with access to the Dataset (directly or via Group), excluding Admins.
Below are the User object parameters from the direct_users and all_users arrays:
id
integerUser ID.
username
stringUsername.
display_name
stringUser's first and last name. (Returned in direct_users.)
first_name
stringUser's first name. (Returned in all_users.)
last_name
stringUser's last name. (Returned in all_users.)
can_edit
stringWhether the User can edit the Dataset. ("Y", "N", or "N/A")

3. Configure Group_Dataset Associations

The /api/group_dataset endpoint retrieves which Groups have access to which Datasets, and allows granting and removing that access. Each data entry has a unique ID and represents a single Group-to-Dataset mapping.

3.1. Retrieve Groups With Access to Dataset

NOTE: The ID of each group_dataset data entry is unique and can be used to delete existing entries.

  • A GET request to /api/group_dataset returns all Group-to-Dataset access mappings.
  • A GET request to /api/group_dataset/id/<id> returns a single Group-to-Dataset mapping by ID.
  1. Item: group_dataset
  2. Method: GET
  3. Filter the results with the following parameters:
    • group: The ID of the Group.
    • dataset: The ID of the Dataset.
  4. Enter an API Token.
  5. [Run request].

Example Response

 

{
  "group_datasets": [
    {
      "id": 1,
      "group": 2,
      "dataset": 53,
      "edit_access": "Yes"
    },
    {
      "id": 12,
      "group": 4,
      "dataset": 204,
      "edit_access": "No"
    },
    {
      "id": 8,
      "group": 14,
      "dataset": 78,
      "edit_access": "No"
    }
  ]
}

Fields Description

Field NameValue TypeDescription
id
integerThe ID of the group_dataset data entry.
group
integerThe ID of the Group.
dataset
integerThe ID of the Dataset.
edit_access
stringWhether the Group's members can edit the Dataset. ("Yes"/"No")

3.2. Grant Group Access to Dataset

NOTE: A Group cannot be granted access to a Dataset it already has access to. To change a Group's edit access, remove the existing mapping first, then create a new one.

A POST request to /api/group_dataset grants a Group access to the Dataset.

  1. Item: group_dataset
  2. Method: POST
  3. Enter the ID of an already existing group_dataset data entry.
  4. Choose JSON request and provide the following values:
    • group: The ID of the Group to grant access to.
    • dataset: The ID of the Dataset.
    • edit_access: Whether the Group's members can edit the Dataset. ("Yes"/"No", optional, default "No".)
  5. Enter an API Token.
  6. [Run request]

3.3. Remove Group Access from Dataset

A DELETE request to /api/group_dataset/id/<id> removes a Group's access to the Dataset.

  1. Item: group_dataset
  2. Method: DELETE
  3. Enter the ID of the group_dataset data entry to be deleted.
  4. Enter an API Token.
  5. [Run request]

4. Configure User_Dataset Associations

The /api/user_dataset endpoint retrieves which Users have access to which Datasets, and allows granting and removing that access. Each data entry has a unique ID and represents a single User-to-Dataset mapping.

4.1. Retrieve Users With Access to Dataset

NOTE: The ID of each user_dataset data entry is unique and can be used to delete existing entries.

  • A GET request to /api/user_dataset returns all User-to-Dataset access mappings.
  • A GET request to /api/user_dataset/id/<id> returns a single User-to-Dataset mapping by ID.
  1. Item: user_dataset
  2. Method: GET
  3. Filter the results with the following parameters:
    • user: The ID of the User.
    • dataset: The ID of the Dataset.
  4. Enter an API Token.
  5. [Run request]

Example Response 

{
  "user_datasets": [
    {
      "id": 1,
      "user": 2,
      "dataset": 53,
      "edit_access": "Yes"
    },
    {
      "id": 12,
      "user": 4,
      "dataset": 204,
      "edit_access": "No"
    },
    {
      "id": 8,
      "user": 14,
      "dataset": 78,
      "edit_access": "No"
    }
  ]
}

Fields Description

Field NameValue TypeDescription
id
integerThe ID of the user_dataset data entry.
user
integerThe ID of the User.
dataset
integerThe ID of the Dataset.
edit_access
stringWhether the User can edit the Dataset. ("Yes"/"No")

4.2. Grant User Access to Dataset

NOTES:

  • A User cannot be granted access to a Dataset they already have access to. To change a User's edit access, remove the existing mapping first, then create a new one.
  • Admin Users cannot be assigned Dataset access directly (they already have full access).

A POST request to /api/user_dataset grants a User access to the Dataset.

  1. Item: user_dataset
  2. Method: POST
  3. Enter the ID of an existing user_dataset data entry.
  4. Choose JSON request and provide the following values:
    • user: The ID of the User to grant access to.
    • dataset: The ID of the Dataset.
    • edit_access: Whether the User can edit the Dataset. ("Yes"/"No", optional, default "No".)
  5. Enter an API Token.
  6. [Run request]

4.3. Remove User Access from Dataset

A DELETE request to /api/user_dataset/id/<id> removes a User's access to the Dataset.

  1. Item: user_dataset
  2. Method: DELETE
  3. Enter the ID of the user_dataset data entry to be deleted.
  4. Enter an API Token.
  5. [Run request]