- Previous: File System API
- Up: Overview
- Next: Events API
Permissions API
The Permissions API allows you to list, set, and remove folder permissions for users and groups. Please refer to the table below for details on our different permission levels.
Permission Levels
Actions | Viewer Only | Viewer | Editor | Full | Owner |
---|---|---|---|---|---|
Preview Files in WebUI | |||||
Download/Read Files, Folders | |||||
Copy Files, Folders | |||||
Upload/Edit Files, Folders | |||||
Create Sub-folder | |||||
Rename Files, Folders | |||||
Create Upload Links | |||||
Move Files, Folders | |||||
Delete Files, Folders | |||||
Edit Folder Sharing |
URL Encoding
The individual elements of folder paths in the URL must be URL encoded. However the intervening forward slashes must not be escaped. For example, this path: Shared/example?path/$file.txt should be encoded as Shared/example%3Fpath/%24file.txt
API Methods
Get Effective Permissions for a User
Gets the effective permissions for a user for a given folder. This effective permission takes into account both user and group permissions that apply to the given user, along with permission inheritance. If a username is not specified, the permissions for your account (the account associated with this API key) will be returned.
Request Parameters
Parameter | Description | Required | Possible Values |
---|---|---|---|
folder | Path to folder | Yes | Must contain the absolute path of the desired folder |
Method-Specific Response Codes
Error Code | Error Message | HTTP Code | Troubleshooting |
---|---|---|---|
Forbidden | User is not authorized to manage resources | 403 | Acting user has no access to this folder |
Request Examples
GET /pubapi/v1/perms/user/jsmith?folder=/Shared/Documents HTTP/1.1 Host: apidemo.egnyte.com Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v --request GET -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" https://apidemo.egnyte.com/pubapi/v1/perms/user/jsmith?folder=/Shared/Documents
Sample Response
{ "permission": "Full" }
Get Folder Permissions
This method gets the permissions for a given folder.
Method-Specific Response Codes
Error Code | Error Message | HTTP Code | Troubleshooting |
---|---|---|---|
Forbidden | User is not authorized to manage resources | 403 | Acting user has no access to this folder |
Request Examples
GET /pubapi/v2/perms/Shared/Documents HTTP/1.1 Host: apidemo.egnyte.com Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v --request GET -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" https://apidemo.egnyte.com/pubapi/v2/perms/Shared/Documents
Sample Response
{ "userPerms": { "jsmith": "Full", "ajones": "Viewer" }, "groupPerms": { "All Administrators": "Owner", "Marketing Team": "Editor" }, "inheritsPermissions": true }
Set Folder Permissions
This method sets new permissions entries for users or groups on a given folder. The API is a delta API and can be used to incrementally add or remove permissions. Permissions for existing users or groups can be removed with this API by passing a "None" permission.
Request Parameters
Parameter | Description | Required | Possible Values |
---|---|---|---|
userPerms | Map of user to permission value | No (either userPerms or groupPerms must be provided) | An object where each key is a username and the value is a permission. Possible permissions include: None, Viewer Only, Viewer, Editor, Full, Owner |
groupPerms | Map of group name to permission value | No - either userPerms or groupPerms must be provided | An object where each key is a group name and the value is a permission. Possible permissions include: None, Viewer Only, Viewer, Editor, Full, Owner |
inheritsPermissions | Whether permissions should be inherited from the parent folder | No - this option only should be passed when changing the permissions inheritance status for a folder. | A Boolean, true or false |
keepParentPermissions | When disabling permissions inheritance with inheritsPermissions, this options determines whether previously inherited permissions from parent folders should be copied to this folder. | No - this option should only be passed when passing inheritsPermissions as false | A Boolean, true or false |
Method-Specific Response Codes
Error Code | Error Message | HTTP Code | Troubleshooting |
---|---|---|---|
Forbidden | User is not authorized to manage resources | 403 | User cannot modify permissions (not an admin and does not have Owner permissions to folder). |
Error Code | Error Message | HTTP Code | Troubleshooting |
Bad Request | This group has more than ... member(s). Only Administrators are allowed to manage large group permissions. | 400 | Giving permissions to a large group is allowed only for Admins. The default threshold for a group to be "large" is 2,000. Please, contact Egnyte Support if you believe the threshold value should be different for your domain |
Request Examples
POST /pubapi/v2/perms/Shared/Documents HTTP/1.1 Host: apidemo.egnyte.com Authorization: Bearer 68zc95e3xv954u6k3hbnma3q Content-Type: application/json { "userPerms": { "jsmith": "Viewer", "ajones": "Editor" }, "groupPerms": { "Project Team": "Full", "Contractors": "None" } }
curl -v --request POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" -H "Content-Type: application/json" --data '{"userPerms":{"jsmith": "Viewer", "ajones": "Editor"}, "groupPerms":{"Project Team": "Full", "Contractors": "None"}}' https://apidemo.egnyte.com/pubapi/v2/perms/Shared/Documents
Permissions API v1 (Deprecated)
Version 1 of the permissions API is deprecated. Version 2, documented above, is more efficient and allows setting multiple permission levels on a single folder at the same time.
Get Folder Permissions (v1)
This method gets the permissions for a given folder.
Request Parameters
Parameter | Description | Required | Possible Values |
---|---|---|---|
users | List of usernames to report on. If neither users nor groups is set then permissions for all subjects are returned. List items are separated by ‘|’ characters. | Yes | An array of usernames. At least one user or group must be specified. |
groups | List of groups to report on. If neither users nor groups is set then permissions for all subjects are returned. List items are separated by ‘|’ characters. | Yes | An array of groupnames. At least one user or group must be specified. |
Method-Specific Response Codes
Error Code | Error Message | HTTP Code | Troubleshooting |
---|---|---|---|
Forbidden | User is not authorized to manage resources | 403 | Acting user has no access to this folder |
Request Examples
GET /pubapi/v1/perms/folder/MyFolder?users=jsmith|ajones&groups=All%20Power%20Users HTTP/1.1 Host: apidemo.egnyte.com Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
curl -v --request GET -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" https://apidemo.egnyte.com/pubapi/v1/perms/folder/MyFolder?users=jsmith|ajones&groups=All%20Power%20Users
Sample Response
{ "users": [ { "subject": "jsmith", "permission": "Full" }, { "subject": "ajones", "permission": "Viewer" } ], "groups": [ { "subject": "All Power Users", "permission": "Editor" } ] }
Set Folder Permissions (v1)
This method sets the effective permission level for specific users or groups on a given folder.
Request Parameters
Parameter | Description | Required | Possible Values |
---|---|---|---|
users | List of usernames to set permissions for | Yes | An array of usernames. At least one user or group must be specified. |
groups | List of groupnames to set permissions for | Yes | An array of groupnames. At least one user or group must be specified. |
permission | Permission level to set | Yes | None, Viewer Only, Viewer, Editor, Full, Owner |
Method-Specific Response Codes
Error Code | Error Message | HTTP Code | Troubleshooting |
---|---|---|---|
Forbidden | User is not authorized to manage resources | 403 | User cannot modify permissions (not an admin and does not have Owner permissions to folder). |
Bad Request | This group has more than ... member(s). Only Administrators are allowed to manage large group permissions. | 400 | Giving permissions to a large group is allowed only for Admins. |
Request Examples
POST /pubapi/v1/perms/folder/Shared/MyFolder HTTP/1.1 Host: apidemo.egnyte.com Authorization: Bearer 68zc95e3xv954u6k3hbnma3q Content-Type: application/json { "users": [ "jsmith", "ajones" ], "permission": "Viewer" }
curl -v --request POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" -H "Content-Type: application/json" --data '{"users":["jsmith","ajones"], "permission":"Viewer"}' https://apidemo.egnyte.com/pubapi/v1/perms/folder/Shared/MyFolder
- Previous: File System API
- Up: Overview
- Next: Events API
Docs Navigation
- Overview
- Getting Started
- Authentication
- File System API
- Permissions API
- Events API
- Search API
- Links API
- Workflow API
- User Management API
- Group Management API
- Audit Reporting API v2
- Trash API
- Comments API
- Metadata API
- Embedded UI API
- Bookmarks API
- User Insights API
- Folder Options API
- Project Folder API
- UI Integration Framework
- Controlled Document Management API
- Best Practices
- Mobile Development
- Other Applications
- Webhooks
- Secure and Govern API
- Audit Reporting API V1
- MSP API