AccessControls define the rights and options of a Principal to a given Item AccessControls define a set of rights - such as CanUpload, CanDownload, CanView - as well as a set of options - such as NotifyOnUpload - that applies to a given Principal (user) and Item (folder). In ShareFile, Access Controls are only associated with Folders. Access Controls can be inherited on Children Folders, or Children can override the list of the Parent. The ACLs are not additive - either the Child uses the list of the Parent, or it defines a new list.
GET https://account.sf-api.com/sf/v3/AccessControls(principalid=principalid,itemid=itemid)
Retrieves a single Access Control entry for a given Item and Principal
| principalid | String | Principal Identifier |
| itemid | String | Item Identifier |
Returns: A single AccessControl object matching the query
GET https://account.sf-api.com/sf/v3/Items(id)/AccessControls
Retrieves the Access Control List for a given Item.
| id | String | Item identifier |
Returns: Access Control List of the given object ID.
POST https://account.sf-api.com/sf/v3/Items(id)/AccessControls?recursive=false
{
"Principal":{"url":"https://account.sf-api.com/v3/Groups(id)"},
"CanUpload":true,
"CanDownload":true,
"CanView":true,
"CanDelete":true,
"CanManagePermissions":true,
"Message":"Message"
}
Creates a new Access Controls entry for a given Item. Access controls can only define a single Principal, which can be either a Group or User. The 'Principal' element is specified as an object - you should populate either the URL or the ID reference. If CanDownload is set to true, CanView will automatically be set to true. If CanDownload is set to false, CanDelete will be set to false. In order for a user/group to be able to manage permissions, they must be able to upload, download, and delete. Otherwise it will be set to false. This endpoint can return an AsyncOperation if the request is to be fulfilled asynchronously
| id | String | Item identifier |
| accessControl | AccessControl | AccessControl to create |
| recursive | Boolean | Indicates whether the operation applies to sub-folders of this item. Default is "false", only the target object is modified |
| message | String | Message sent of other principals with rights on the modified Item. This parameter can be sent as a URI param, or as part of the JSON description, added to the AccessControl element described there. |
| sendDefaultNotification | Boolean | Indicates whether or not the system should send a default notification to the Principals. Default is "false" |
Returns: the created or modified AccessControl instance, or AsyncOperation
PATCH https://account.sf-api.com/sf/v3/Items(id)/AccessControls?recursive=false
{
"Principal":{"Email":"user@domain.com"},
"CanUpload":true,
"CanDownload":true,
"CanView":true,
"CanDelete":true,
"CanManagePermissions":true
}
Updates an existing Access Controls of a given Item. The Principal element cannot be modified, it is provided in the Body to identity the AccessControl element to be modified. You can provide an ID, Email or URL on the Principal object. This endpoint can return an AsyncOperation if the request is to be fulfilled asynchronously
| id | String | Item identifier |
| accessControl | AccessControl | |
| recursive | Boolean | Indicates whether the operation applies to sub-folders of this item. Default is "false", only the target object is modified |
Returns: the created or modified AccessControl instance, or AsyncOperation
DELETE https://account.sf-api.com/sf/v3/AccessControls(principalid=id,itemid=id)
Deletes an AccessControl entry by itemID and principalID. This method does not return any object, a 204 (No Content) response indicates success.
| principalid | String | Principal Identifier |
| itemid | String | Item Identifier |
POST https://account.sf-api.com/sf/v3/Items(id)/AccessControls/BulkSet
{
"NotifyUser":true,
"NotifyMessage":"msg",
"AccessControlParams":
[
{
"AccessControl":
{
"Principal" : { "Id":"existing_user_id" },
"CanUpload" : true,
"CanDownload" : false,
"CanView" : true
},
"NotifyUser":false
},
{
"AccessControl":
{
"Principal" : { "Id":"group_id" },
"CanUpload" : false,
"CanDownload" : true,
"CanView" : true
},
"Recursive":true
},
{
"AccessControl":
{
"Principal" : { "Email":"new_or_existing_user@a.com" },
"CanUpload" : false,
"CanDownload" : true,
"CanView" : true
}
}
]
}
All the AccessControls are created or updated for a single Item identified by the Item id in the URI. AccessControl.Item Ids are not allowed. If an AccessControl doesn't specify NotifyUser or NotifyMessage property their values are inherited from the corresponding top-level properties. The Principal can be identified by Id or Email (Users). If a User with the specified email does not exist it will be created. Defaults for NotifyUser and Recursive are false. See AccessControlsBulkParams for other details.
| id | String | Item id |
| bulkParams | AccessControlsBulkParams | AccessControlsBulkParams |
Returns: AccessControlBulkResult
POST https://account.sf-api.com/sf/v3/AccessControls/BulkSetForPrincipal?principalId=my-principal-id
{
"NotifyUser":true,
"NotifyMessage":"msg",
"AccessControlParams":
[
{
"AccessControl":
{
"Item": { "Id": "item-id-1" },
"Principal" : { "Id":"existing_user_id" },
"CanUpload" : true,
"CanDownload" : false,
"CanView" : true
},
"NotifyUser":false
},
{
"AccessControl":
{
"Item": { "Id": "item-id-3" },
"Principal" : { "Id":"group_id" },
"CanUpload" : false,
"CanDownload" : true,
"CanView" : true
},
"Recursive":true
},
{
"AccessControl":
{
"Item": { "Id": "item-id-2" },
"Principal" : { "Email":"new_or_existing_user@a.com" },
"CanUpload" : false,
"CanDownload" : true,
"CanView" : true
}
}
]
}
| principalId | String | Principal id |
| bulkParams | AccessControlsBulkParams | AccessControlsBulkParams |
Returns: AccessControlBulkResult
POST https://account.sf-api.com/sf/v3/AccessControls/Clone
{
"FolderId":"top-level-folder-id",
"PrincipalId":"source-user-or-group-id",
"ClonePrincipalIds":
[
"clone-user-or-group-id-1",
"clone-user-or-group-id-2",
"clone-user-or-group-id-3"
]
}
| accessControlsCloneParams | AccessControlsCloneParams | AccessControlsCloneParams |
Returns: Cloned access controls
POST https://account.sf-api.com/sf/v3/Items(grandparentid)/AccessControls/BulkDelete
["id1","id2"]
| folderId | String | Id of Parent item |
| principalIds | String[] | List of IDs of principals to be deleted |
POST https://account.sf-api.com/sf/v3/AccessControls/BulkDeleteForPrincipal?principalId=xxxxx
["id1","id2"]
| principalId | String | Id of Principal |
| folderIds | String[] | List of IDs of folders |
POST https://account.sf-api.com/sf/v3/Items(id)/AccessControls/NotifyUsers
{
UserIds: ["id1", "id2"],
CustomMessage: "Message content goes here"
}
All users should have access to the parent folder
| folderId | String | ID of Parent item |
| notifyUsersParams | NotifyUsersParams | Parameter container |
POST https://account.sf-api.com/sf/v3/Items(id)/AccessControls/NotifyUsersPreview
| folderId | String | ID of Parent item |
| notifyUsersParams | NotifyUsersParams | Parameter container |