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:
| Permission | Access Level Granted | Automatically Also Includes/Implies Permissions |
|---|---|---|
admin | Able to manage Folder Behaviors, Permissions, and Notifications for the folder. Also grants all other permissions. | bundle, full, writeonly, readonly, list, history |
bundle | Able to share files and folders via a Bundle (share link). | readonly, list |
full | Able to read, write, move, delete, and rename files and folders. Also grants the ability to overwrite files upon upload. | writeonly, readonly, list |
history | Able to view the history of files and folders and to create email notifications for themselves. | list |
list | Able to list files and folders, but not download. | none |
readonly | Able to list, preview, and download files and folders. | list |
readonly_site_admin | Able to behave as a read-only Site Admin on a given child site. Only applies to child sites. | readonly, list, history |
site_admin | Able to behave as a Site Admin on a given child site. Only applies to child sites. | bundle, full, writeonly, readonly, list, history |
writeonly | Able to upload files, create folders and list subfolders the user has write permission to. | none |
List Permissions
Command
files-cli permissions list
Output
Outputs a list of Permission objects according to the output format.
Authorization Requirement
Available to all authenticated keys or sessions.
Flags
| Flag | Description |
|---|---|
| --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
Create Permission
Command
files-cli permissions create
Output
Outputs a Permission object according to the output format.
Authorization Requirement
Available to all authenticated keys or sessions.
Flags
| Flag | Description |
|---|---|
| --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. |
Delete Permission
Command
files-cli permissions delete
Output
No output is returned.
Authorization Requirement
Available to all authenticated keys or sessions.
Flags
| Flag | Description |
|---|---|
| --id= int64 Required | Permission ID. |
The Permission Object
Some of the commands above return a Permission object. The attributes of this object are listed below.
| Attribute | Description |
|---|---|
| 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 |