• Register

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 OnlyViewer Editor Full Owner
Preview Files in WebUI yes yes yes yes yes
Download/Read Files, Folders yes yes yes yes
Copy Files, Folders   yes yes yes
Upload/Edit Files, Folders   yes yes yes
Create Sub-folder   yes yes yes
Rename Files, Folders   yes yes yes
Create Upload Links   yes yes yes
Move Files, Folders     yes yes
Delete Files, Folders     yes yes
Edit Folder Sharing       yes

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.

GET/pubapi/v1/perms/user/{username}

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 MessageHTTP CodeTroubleshooting
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.

GET /pubapi/v2/perms/{Full Path to Folder}

Method-Specific Response Codes

Error Code Error MessageHTTP CodeTroubleshooting
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.

POST /pubapi/v2/perms/{Full Path to Folder}

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 MessageHTTP CodeTroubleshooting
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 MessageHTTP CodeTroubleshooting
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.

GET /pubapi/v1/perms/folder/{Full Path to 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 MessageHTTP CodeTroubleshooting
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.

POST /pubapi/v1/perms/folder/{Full Path to 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 MessageHTTP CodeTroubleshooting
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

version 33 as of 1 year ago by chapman