Management

Manage Collection Permissions

Collections allow users to organize Reports related to a team, project, or common theme. Use the steps below to manage access to Collections in your Workspace. You can update the default Workspace access as well as individual Member or Group access for a Collection.

Endpoints used

.../{workspace}/spaces/{space_token}
Supported methods:

PATCH: update the default access level

.../{workspace}/spaces/{space_token}/permissions
Supported methods:

GET: returns a list of collection permissions
POST: creates a new permission for a workspace member

.../{workspace}/spaces/{space_token}/permissions/{permission_token}
Supported methods:

GET: returns the collection permission
PATCH: updates the collection permission
DELETE: removes the collection permission

How this example works

This code example encapsulates updating the default access for a collection, granting access to an individual, updating access, and then removing access. This example focuses on permissions for a workspace member however the same actions can be taken on a group by providing UserGroup instead of Account to the accessor_type field.

To try it yourself

Download the example code to a .py file
Input the API token, API secret, Workspace name, and other custom information as needed. Follow these steps to create an API token.
Save the .py file in your desired directory
Open the terminal and navigate to that directory
Run the command python3 {file_name}.py
All of our Python recipes require Python 3

import json
import requests

from requests.auth import HTTPBasicAuth

host = 'https://app.mode.com'
workspace = 'workspace_name'
username = 'api_token'
password = 'api_secret'
headers = {'Content-Type': 'application/json'}

# action can be 'restricted', 'view', or 'edit'
def update_default_collection_permission(collection_token, action):
  url = '%s/api/%s/spaces/%s' %(host, workspace, collection_token)
  payload = {
    'space': {
      'default_access_level': action
    }
  }

  response = requests.patch(url, auth=HTTPBasicAuth(username, password), headers=headers, json=payload)
  return response.json()

def get_permission_token(collection_token, user_token):
  url = '%s/api/%s/spaces/%s/permissions' %(host, workspace, collection_token)

  response = requests.get(url, auth=HTTPBasicAuth(username, password), headers=headers)
  body = response.json()

  if body['_embedded'] and body['_embedded']['entitlements']:
    return next((entitlement['token'] for entitlement in body['_embedded']['entitlements'] if entitlement['accessor_type'] == 'Account' and entitlement['accessor_token'] == user_token), None)

# action can be 'view' or 'edit'
def give_member_collection_permission(collection_token, user_token, action):
  url = '%s/api/%s/spaces/%s/permissions' %(host, workspace, collection_token)
  payload = {
    'permission': {
      'action': action,
      'accessor_type': 'Account',
      'accessor_token': user_token
    }
  }

  response = requests.post(url, auth=HTTPBasicAuth(username, password), headers=headers, json=payload)
  return response.json()

def update_member_collection_permission(collection_token, user_token, action):
  permission_token = get_permission_token(collection_token, user_token)
  url = '%s/api/%s/spaces/%s/permissions/%s' %(host, workspace, collection_token, permission_token)
  payload = {
    'permission': {
      'action': action
    }
  }

  response = requests.patch(url, auth=HTTPBasicAuth(username, password), headers=headers, json=payload)
  return response.json()

def remove_member_collection_permission(collection_token, user_token):
  permission_token = get_permission_token(collection_token, user_token)
  url = '%s/api/%s/spaces/%s/permissions/%s' %(host, workspace, collection_token, permission_token)

  response = requests.delete(url=url, auth=HTTPBasicAuth(username, password), headers=headers)
  return response.json()

update_default_collection_permission('collection_token', 'view')
give_member_collection_permission('collection_token', 'user_token', 'view')
update_member_collection_permission('collection_token', 'user_token', 'edit')
remove_member_collection_permission('collection_token', 'user_token')
const request = require('request-promise');

const host = 'https://app.mode.com';
const workspace = 'workspaceName';
const username = 'apiToken';
const password = 'apiSecret';

// action can be 'restricted', 'view', or 'edit'
const updateDefaultCollectionPermission = async (collectionToken, userToken, action) => {
  const payload = {
    space: {
      default_access_level: action
    }
  }

  return await request({
    method: 'PATCH',
    url: `${host}/api/${workspace}/spaces/${collectionToken}`,
    auth: { username, password },
    json: true,
    body: payload,
  });
};

const getPermissionToken = async (collectionToken, userToken) => {
  const res = await request({
    method: 'GET',
    url: `${host}/api/${workspace}/spaces/${collectionToken}/permissions`,
    auth: { username, password }
  });

  if (res['_embedded'] && res['_embedded']['entitlements']) {
    const entitlement = res['_embedded']['entitlements'].find((entitlement) => {
      return entitlement['accessor_type'] === 'Account' && entitlement['accessor_token'] === userToken;
    });
    if (entitlement) {
      return entitlement['token'];
    }
  }
}

// action can be 'view' or 'edit'
const giveMemberCollectionPermission = async (collectionToken, userToken, action) => {
  const payload = {
    permission: {
      action: action,
      accessor_type: 'Account',
      accessor_token: userToken
    }
  };

  return await request({
    method: 'POST',
    url: `${host}/api/${workspace}/spaces/${collectionToken}/permissions`,
    auth: { username, password },
    json: true,
    body: payload,
  });
};

const updateMemberCollectionPermission = async (collectionToken, userToken, action) => {
  const payload = {
    permission: {
      action: action
    }
  };

  const permissionToken = await getPermissionToken(collectionToken, userToken);

  return await request({
    method: 'PATCH',
    url: `${host}/api/${workspace}/spaces/${collectionToken}/permissions/${permissionToken}`,
    auth: { username, password },
    json: true,
    body: payload,
  });
};

const removeMemberCollectionPermission = async (collectionToken, userToken) => {
  const permissionToken = await getPermissionToken(collectionToken, userToken);

  return await request({
    method: 'DELETE',
    url: `${host}/api/${workspace}/spaces/${collectionToken}/permissions/${permissionToken}`,
    auth: { username, password }
  });
};

updateDefaultCollectionPermission('collectionToken', 'view');
giveMemberCollectionPermission('collectionToken', 'userToken', 'view');
updateMemberCollectionPermission('collectionToken', 'userToken', 'edit');
removeMemberCollectionPermission('collectionToken', 'userToken');