Permissions

A Permission object represents a grant of access permission on a specific Path to a User or Group.

They can be optionally recursive or nonrecursive into the subfolders of that path.

A Permission may be applied to a User or a Group, but not both at once.

The following table sets forth the available Permission types:

PermissionAccess Level GrantedAutomatically Also Includes/Implies Permissions
adminAble to manage Folder Behaviors, Permissions, and Notifications for the folder. Also grants all other permissions.bundle, full, writeonly, readonly, list, history
bundleAble to share files and folders via a Bundle (share link).readonly, list
fullAble to read, write, move, delete, and rename files and folders. Also grants the ability to overwrite files upon upload.writeonly, readonly, list
historyAble to view the history of files and folders and to create email notifications for themselves.list
listAble to list files and folders, but not download.none
readonlyAble to list, preview, and download files and folders.list
readonly_site_adminAble to behave as a read-only Site Admin on a given child site. Only applies to child sites.readonly, list, history
site_adminAble to behave as a Site Admin on a given child site. Only applies to child sites.bundle, full, writeonly, readonly, list, history
writeonlyAble to upload files, create folders and list subfolders the user has write permission to.none

List Permissions

SDK Function

Permission.list()

Return Object

ListIterator<Permission>

Authorization Requirement

Available to all authenticated keys or sessions.

Function Arguments

ArgumentDescription
path
string		Permission path. If provided, will scope all permissions(including upward) to this path.
include_groups
boolean		If searching by user or group, also include user's permissions that are inherited from its groups?
group_id
string
partner_id
string
user_id
string

Additional Arguments

Example Request

import com.files.ListIterator;
import com.files.exceptions.*;
import com.files.exceptions.ApiErrorException.*;
import com.files.models.Permission;

try {
  HashMap<String, Object> parameters = new HashMap<>();
  parameters.put("path", "example");
  
  ListIterator<Permission> permissions = Permission.list(parameters);
  for (Permission permission : permissions.listAutoPaging()) {
    // Operate on permission
  }
} catch (NotAuthenticatedException e) {
  System.out.println("Authentication Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
} catch (SdkException e) {
  System.out.println("Unknown Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
}

Create Permission

SDK Function

Permission.create()

Return Object

Permission

Authorization Requirement

Available to all authenticated keys or sessions.

Function Arguments

ArgumentDescription
path
string
Required		Folder path
group_id
int64		Group ID. Provide group_name or group_id
group_ids
string		Group IDs when the permission requires multiple groups. If sent as a string, it should be comma-delimited.
permission
string		Permission type. Can be admin, full, readonly, writeonly, list, or history
recursive
boolean		Apply to subfolders recursively?
partner_id
int64		Partner ID if this Permission belongs to a partner.
user_id
int64		User ID. Provide username or user_id
username
string		User username. Provide username or user_id
group_name
string		Group name. Provide group_name or group_id
site_id
int64		Site ID. If not provided, will default to current site. Used when creating a permission for a child site.

Example Request

import com.files.exceptions.*;
import com.files.exceptions.ApiErrorException.*;
import com.files.models.Permission;

try {
  HashMap<String, Object> parameters = new HashMap<>();
  parameters.put("path", "path");
  
  Permission permission = Permission.create(parameters);
  // Operate on permission
} catch (NotAuthenticatedException e) {
  System.out.println("Authentication Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
} catch (SdkException e) {
  System.out.println("Unknown Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
}

Delete Permission

SDK Function

permission.delete();

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Example Request

import com.files.exceptions.*;
import com.files.exceptions.ApiErrorException.*;
import com.files.models.Permission;

try {
  Permission permission = Permission.list()[0];
  permission.delete(null);
} catch (NotAuthenticatedException e) {
  System.out.println("Authentication Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
} catch (SdkException e) {
  System.out.println("Unknown Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
}

The Permission Object

Some of the functions above return a Permission object. The attributes of this object are listed below.

AttributeDescription
id
int64		Permission ID
path
string		Path. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
user_id
int64		User ID
username
string		Username (if applicable)
group_id
int64		Group ID
group_name
string		Group name (if applicable)
group_ids
array(int64)		Group IDs when this permission requires multiple groups
group_names
array(string)		Group names when this permission requires multiple groups
partner_id
int64		Partner ID (if applicable)
partner_name
string		Partner name (if applicable)
permission
string		Permission type. See the table referenced in the documentation for an explanation of each permission.
Possible values: full, readonly, writeonly, list, history, admin, bundle, site_admin, readonly_site_admin, previewonly
recursive
boolean		Recursive: does this permission apply to subfolders?
site_id
int64		Site ID