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.
Part 1: Choosing 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 typically 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 have the ability to provision access using Merge’s permissions and roles Common Models
1b: Individual user authentication
Recommended for CRM: 📖 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 via their API.
Access will always be updated to match the third-party configuration
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 delays from reaching third-party rate limits.
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
| Third-party webhook available? | Highest available Permissions polling frequency |
Google Drive | ✅ | Every 24 hours |
Dropbox | ✅ | Every 3 hours |
Box | ✅ | Every 3 days |
Sharepoint | ❌ | Every 24 hours |
OneDrive | ❌ | Every 3 hours |
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:
Subscribe to Merge's live system status in case of rare system outages.
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. This can help you decide whether to trust the current ACL data.
Issue Tracking System: Data may fail to update for various reasons including your users’ API credentials expiring, missing permissions or API outages. Merge automatically reports on issues via the Issues endpoint.
Enable Merge webhooks
Linked Account Issues: to receive real-time alerts when an issue occurs
Linked Account Synced: to receive real-time alerts when selected Linked Accounts are synced.
Common Model Synced: to receive real-time alerts when selected Common Models are synced e.g., Permissions
Part 4: Summary
Admin auth is recommended for optimal performance and control when available
Use Merge's Permissions and Roles models to determine user & group access.
Merge prioritizes real-time updates via webhooks but we recommend you implement a combination of webhooks and polling
Failures are logged and surfaced via issues endpoint & issues webhooks
Part 5: 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 near real time with the change.
If the integration does not support webhooks Merge will capture this change upon the next periodic 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 will detect and alert you of sync failures via our 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.