Overview

Merge provides flexible and precise ways to handle Access Control Lists (ACLs) across many categories of integrations. This guide will help you understand how to configure ACLs when using Merge, including authentication strategies, how to determine user access, ACL propagation frequency, and failure handling.

Quick summary:

Admin authentication is recommended for optimal performance and control if allowed by your product design
Use Merge's Permissions and Roles model to configure user & group access
Merge prioritizes real-time updates via webhooks whenever available by the API provider, but we also recommend polling regularly for updates
Failures are logged and surfaced via issues endpoint & issues webhooks

Part 1: Choose a level of authentication

ACL enforcement depends on access level of the user that is authenticating whether that is admin level or individual user authentication.

1a: Admin authentication

Required for HRIS & ATS

Recommended for 📖 File Storage ACLs and 📖 Ticketing ACLs

With admin authentication, Merge pulls all data that the admin has access to, which includes most of the data available across an organization—except private files. This approach is recommended because:

Only a single admin user needs to connect the integration, leading to faster onboarding for entire organizations
You only need to sync data once, reducing risk of hitting third-party rate limits
You can provision user level access using Merge’s permissions and roles Common Models

1b: Individual user authentication

Recommended for 📖 CRM ACLs

With individual user authentication, the third-party platform fully manages access controls, ensuring that the user only has access to their own data. This approach is recommended when the third-party platform does not expose access to granular permissions in their API.

Access will always be in sync with the third-party ACLs
You sync data for each individual user that authenticates. Depending on how many users connect in a period of time, syncs run the risk of hitting third-party rate limits and significant delays

Part 2: 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. Some third-party APIs, such as SharePoint enforce strict rate limits e.g., 5,000 single ACL API requests per hour. 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 (milliseconds) wherever the third-party API supports webhooks.

File Storage Permissions sync frequency

The Permissions model is a sub-model on Merge’s File Storage Files and Folders Common Models.

	Third-party webhook supported?	Highest available Permissions polling frequency
Google Drive	✅	Every 1 hour*
Box	✅	Every 3 days
Dropbox	❌ not supported by Dropbox	Every 1 hour
Sharepoint	❌ not support by Sharepoint	Every 24 hours* for objects modified in the last year Every 2 weeks for objects modified over one year ago
OneDrive	❌ not support by OneDrive	Every 1 hour

*This frequency is under review by Merge as of 3/18/25, with enhancements planned

Part 3: Failure handling

Merge has built-in mechanisms to detect and alert you of failures in our syncs including ACL requests that fail. Merge has a fail-open model where we surface data even if syncs fail; the option to configure a fail-closed system is up to you and your implementation.

Regardless, we recommend implementing the following features for failure handling:

Poll for sync status: Make a request to Merge's /sync-status endpoint, which returns an array of sync statuses for all models in a category. Use this to ensure you are retrieving the latest available data.
Issue tracking: Data may fail to update for various reasons including your users’ API credentials expiring, missing permissions or third-party API outages. Merge automatically reports issues via the Issues endpoint.
Enable Merge webhooks to receive real-time alerts
- Linked Account Issues: when an issue occurs
- Linked Account Synced: when all models for a Linked Accounts are synced
- Common Model Synced: the selected Common Models are synced e.g., Permissions
Subscribe to Merge's live system status in case of rare system outages.

FAQs

If someone’s access gets revoked, how long does that take to propagate?

If the integration supports third-party webhooks and assuming you set up a Merge Common Model synced webhook, you will receive a webhook with the change in real time
If the integration does not support webhooks Merge will capture this change upon the next scheduled sync. Merge kicks off periodic syncs for production Linked Accounts at varying rates. This does not mean we are able to pull data at precisely those rates. The time to sync data depends on integration factors such as the third-party API rate limits, support of timestamp filters, the number of objects in the system, etc. The frequency at which Merge executes a periodic sync is specific to the integration and Common Model; see sync frequency documentation.

What happens when there is an issue? What is a failure mode?

Merge has a fail-open model where we surface data even if syncs fail; the option to configure a fail-closed system is up to your implementation.
Merge alerts users of sync failures via the issues endpoint & issues webhooks.

Are there any Time-To-Live (TTLs) for data?

Merge does not enforce TTLs, the option to configure TTLs is up to your implementation.
Merge only prevents data access when Scopes are disabled for a Common Model. If a Merge Common Model Scope is disabled for 30 consecutive days, we will delete the underlying data to minimize storage of inactive and used data.

Is sync status tracked at the corpus level, or can we get it per file or resource?

To see when a Common Model was last modified, see the modified_at field
To see when a Common Model was most recently synced and the status of the last sync see /sync-status fields last_sync_result and last_sync_finished

What happens if a file's content is updated, but its permissions are not?

When ingesting file content, we recommend taking a "snapshot" and tying it to the permissions at that time
If the file content is updated, but permissions are not (indicated by last_sync_result and last_sync_finished ), you must decide to either show the previous snapshot, or the newer version of the file

Deleted Data Detection

What are Merge's sync statuses?

Ticketing Access Control List (ACLs)

CRM Access Control List (ACLs)

File Storage Access Control List (ACLs)