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 Knowledge Base API

1. The subject requesting access: Users or Groups

2. The Object to be Accessed: Articles or Containers

3. The permissions allowed: Read, Write, Owner

Integration support for ACLs

Not all Knowledge Base integrations support ACLs. More specifically - Notion does not natively support ACLs via API.

We recommend either user-based authentication approach (non-admin) or managing ACLs on your side for Notion. For more guidance on how to manage ACLs on your side, review our guide:

📄 Implementing Customer-Managed Access Control Lists (ACLs) for Knowledge Base

How to determine article or container access

Fetch the articles(s) or containers(s) of interest: GET /articles and GET /containers. View the permissions array: Articles.permissions and Containers.permissions which represents a user's or group's access to a Articles or Container.

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 parent group that will also have access to the group: group.parent_groups. GET /groups/{id} to see the members of the parent group. This process must be repeated until parent_groups is empty

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

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 an article, and similarly will not have a group or user id.

3. A permissions object of “GROUP” indicates that anyone in the group has access to an article. This object will have a group id.

4. A permissions object of “USER” indicates that this User has access to an article.

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 an article or container: 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.

Knowledge Base Permissions sync frequency

The Permissions model is a sub-model on Merge’s Knowledge Base Articles and ar Common Models. Permissions will be updated based on your sync frequency.