Paragon vs Merge: Different Approaches to File Storage Permissions

Integrating with file storage providers for RAG and agent context use cases starts off simple. You pull down your users' files from their Google Drive, SharePoint, Notion, etc., and run it through your preprocessing and indexing in your RAG pipeline.

But one step that complicates file storage integrations is file permissions. Unlike CRM data or meeting transcript data, files can have complex permissions where users are parts of teams, files are held in folders, and permissions are propagated at every level.

Both Paragon and Merge have managed solutions to syncing your users' file storage data and handling file permissions, Paragon with Managed Sync and Merge with Unified. In this deep dive, we'll go over how Paragon and Merge approach file integration permissions differently and downstream tradeoffs in accuracy, developer experience, and traceability.

Paragon vs Merge's Permissions Approach

Paragon's Approach: Permissions API with FGA

Paragon's Permissions API is built off Fine Grained Authorization (FGA) to manage permissions. Unlike RBAC, ABAC, and ACLs, Fine Grained Authorization uses relationship-based access control (ReBAC) to propagate and reconcile permissions for modeling hierarchies, subsets, and networks. Relationships could be direct to a file (users have a “can_read” relationship with a file) or indirect (users have a “is_member” relationship with a space which has a “can_read” to a folder with a “parent” relationship to a file)

Many file storage solutions, like Google Drive, natively use ReBAC for their permissions. In fact, Google's entire authorization system is built off a ReBAC-based system called Zanzibar.

Paragon manages a highly performant and scalable FGA graph for our customers on our infrastructure as part of the file storage sync. Whenever you initialize a sync to start ingesting your users' files, Paragon starts indexing an FGA graph for that user and keeps that graph up-to-date for their lifetime.

From there, you can use Paragon's Permission Graph as the source of truth and check/query via the Permissions API.

Merge's Approach: ACL with their Files Object

Access Control Lists (or ACLs) are a more simplistic way to convey permissions. When Merge syncs your users' files, they will flatten the native file storage permissions into a list with every user and group with access to that file.

{
  "permissions": [
      {
          "id": "123",
          "remote_id": "102895",
          "created_at": "2020-03-31T00:00:00Z",
          "modified_at": "2020-06-20T00:00:00Z",
          "user": "user_a",
          "type": "USER",
          "roles": [
            "OWNER"
          ]
      },
      {
          "id": "456",
          "remote_id": "102895",
          "created_at": "2020-04-31T00:00:00Z",
          "modified_at": "2020-76-20T00:00:00Z",
          "group": "group_x",
          "type": "GROUP",
          "roles": [
            "READ"

These permissions are a field in Merge's File object, which you can store in your databases or query from Merge's API at retrieval-time.

Accuracy Tradeoffs

File storage permissions are complex. They are also filled with edge cases. Offloading that work while guaranteeing accurate access control is what your integration infrastructure should do.

Paragon's ReBAC-based FGA uses the same native approach as the most popular file storage providers. If Google, SharePoint, Box use ReBAC, the most accurate representation of their permissions should also be ReBAC.

FGA allows Paragon to handle the same nuances that the file storage provider handles. Some real examples of edge cases we covered:

• In Google Drive, files can be shared via links for any user even if they do not have an explicit reader, writer, or owner role. Paragon will pull all of the viewers of a specific file and add permissions to them in your managed FGA.

• In SharePoint, deny lists can override permissions from inheriting folder permissions. Paragon adds these relationships to the FGA graph so synced permissions behave the same way as they would in SharePoint.

Merge's ACLs might not cleanly model these edge cases and may require you to pull down permissions from Merge's file objects, folder objects, and group objects to build logic for these edge cases yourself. This is logic that your integrations platform should do for you, and why Paragon’s managed FGA approach is superior to Merge’s ACL.

Performance Tradeoffs

Performance of your permissions enforcement will depend on implementation, and so choosing to build on Paragon or Merge will warrant different considerations.

On Paragon's managed FGA approach, pulling permissions is a separate API call from pulling file data. If you use Paragon’s Permissions API to check permissions at retrieval time, this will mean an extra API call for retrieval. But considering this pattern, the latency of permission checks can be mitigated to take advantage of Paragon’s managed FGA graph and easy-to-use APIs.

For example, you can use the /batch-check endpoint to check permissions for multiple files with just one API call. For further performance optimizations, you can self-host Paragon’s highly performant infra (capable of handling 10M+ requests/month) in your VPC to reduce latency between your Paragon-managed FGA and your backend infrastructure.

fetch(
  'https://sync.useparagon.com/api/permissions/{syncId}/batch-check',{
	  method: 'POST',
	  body: JSON.stringify({
	    checks: [
	      {
	        object: 'file_a',
	        user: 'user:user-a@example.com',
	        role: 'can_read'
	      },
	      {
	        object: 'file_a',
	        user: 'user:user-b@example.com',
	        role: 'can_read'
	      }
	    ]
  })
}).then(res => res.json())

With Merge, pulling their file object will also pull their ACL permissions, cutting an API call. This will reduce your API calls. However, this difference only becomes significant if you're planning on storing these permissions on your infrastructure, which introduces risk of stale permissions and re-indexing your permissions data from Merge to capture changes. In this case, your engineering team is doing a lot of the heavy-lifting, lifting your integration infrastructure platform should be doing for you.

If you're not planning on storing these permissions to enforce retrievals on your infrastructure at retrieval-time, you lose the benefit of the API savings. Instead, you will have to use Merge's /files endpoint, a similar pattern to Paragon’s Permissions API at retrieval-time. Except unlike Paragon's managed FGA approach, Merge:

1. Does not offer a /batch-check endpoint to check multiple files

2. May require 1+ API calls at retrieval-time to cover edge cases

Auditability Tradeoffs

Integration platforms need to be able to allow you to debug access control. If your users are denied context from a file they should have access to, you should be able to track the lineage of permissions and explain why permissions were enforced on a file asset.

Paragon's FGA approach maps relationships from the file storage integration provider. Using the /expand endpoint, Paragon displays how a user was granted access to a document (role, link, folder, group, etc.). The /expand endpoint has helped us audit exceptions and edge cases like Confluence's deny lists and Google Workspace nested groups.

//The expand shows the different permissions applied to file:abc
//(from direct access to space access)
{
  "tree": {
    "root": {
      "name": "file:abc#can_read",
      "union": {
        "nodes": [
          {
            "name": "file:abc#can_read",
            "leaf": {
              "computed": {
                "userset": "file:abc#viewer"
              }
            }
          },
          {
            "name": "file:abc#can_read",
            "leaf": {
              "tupleToUserset": {
                "tupleset": "file:abc#space",
                "computed": [
                  {
                    "userset": "space:space_xyz#viewer"

Merge, rather than expanding their permissions data, they collapse permissions into their ACL list. While this data structure can be simpler for straightforward use cases, Merge's approach does not allow you to debug permission errors, expand how access was granted, and confirm if a permission was correctly given. Your only choice on Merge is to trust their permissions indexing without the ability to audit how access is given through groups, folders, deny lists, or links.

Wrapping Up

Paragon's approach to file storage permissions is to leverage relationship-based (ReBAC) permissions to map native permissions like groups, folders, and deny lists.

Merge's approach is to flatten permissions and obfuscate native permission relationships.

Both approaches can work for your file storage integrations, but the team at Paragon has high confidence that the FGA approach is the best approach for accuracy, scalable performance, and auditability. Paragon's managed FGA and Permissions API maintains the complexity of mapping native permissions and keeps permission data up-to-date while providing a simple way to access that data.

To learn more about how Paragon fits with your integration strategy, sign up for a free trial or schedule a call with our integrations team.