Overview

An Access Control List is a security feature used in systems (e.g., networking, file systems, databases) to define rules for what users or systems can access specific resources and what actions they can perform on them.

Key Components of an ACL in Merge's File Storage API

1. The subject requesting access: Users or Groups

2. The Object to be Accessed: Files or Folders

3. The permissions allowed: Read, Write, Owner

How to determine file or folder access

Fetch the file(s) or folder(s) of interest: GET /files and GET /folders. View the permissions array: File.permissions and Folder.permissions which represents a user's or group's access to a File or Folder.

Permissions.type = "USER"

Access provisioned individually; the “user” field in the permissions object will be populated with the Merge user UUID.

Permissions.type = "GROUP"

Access provisioned via the group; the “group” field in the permissions object will be populated with the Merge user UUID. For each group in the permissions array, GET /groups/{id}. See the array of users that are members of the group: group.users. Additionally, see the array of child groups that are members of the group: group.child_groups. GET /groups/{id} to see the members of the child group. This process must be repeated until child_groups is empty

Permissions.type = “ANYONE”, “COMPANY”, or “DOMAIN”

1. A permissions object of “ANYONE” will not have a user or group id, and indicates that the item is publicly accessible internally and externally.

2. A permissions object of "COMPANY" indicates that anyone within a company can access a file, and similarly will not have a group or user id.

3. A permissions object of “DOMAIN” indicates that anyone within a given email domain has access to a file. This object will have a group id. The group object will not have users. The domain by which the access is provisioned will be stored in the remote_id field.

Integration nuances for Permissions.type

How to determine available user actions

The Merge permissions.roles array indicates the permissions that a group or user has for a file or folder: Read, Write or Owner.

How ACLs are updated

Merge ensures ACLs are updated as quickly as possible using webhooks and polling.

• Recurring updates via polling: Merge will poll the third-party API. The exact polling rate depends on your plan, the third-party provider’s rate limits (higher-tier plans often have increased limits) and API latency. To see integration specific sync frequencies, check Merge’s sync frequency documentation.

• Real-time updates via webhooks: Merge automatically updates ACLs in near real-time wherever the third-party API supports webhooks. Our webhook notifications typically deliver updates within seconds. While we design our system to be as fast as possible, please note that occasional network or load-related delays may occur. In the event of a webhook delivery failure, Merge will attempt to redeliver multiple times using exponential backoff.

File Storage Permissions sync frequency

The Permissions model is a sub-model on Merge’s File Storage Files and Folders Common Models. Enabling webhooks allows permission changes to be reflected in real-time. This function is only supported by Google Drive and Box. For Sharepoint, OneDrive and Dropbox, permissions will be updated based on your sync frequency.