When building for an Enterprise Search use case on top of Merge’s Knowledge Base category, you must ensure end-users only receive content they are authorized to access.

Merge’s Knowledge Base unified model includes Containers, Articles, and a unified Permissions model (with Users and Groups) where available. However, some teams choose to implement customer-managed ACLs when they need authorization behavior that is:

• More consistent across multiple Knowledge Base integrations

• Easier to administer and troubleshoot in their product

• Explicitly defined by your customers’ business rules, rather than being dependent on the nuances and limitations of each source system’s permissions available via API (for example, at the time of writing, Notion does not expose sufficient permissions data via API to reliably support document-level ACLs)

This is an advanced approach. You should use it when you want your product to enforce your customer’s policy model (often simpler than the source system’s), or when permission coverage or semantics vary by provider configuration.

How to Implement Customer-Managed ACLs

Overview: what you are building

A customer-managed ACL implementation typically has three parts:

1. Content ingestion from Merge (containers, articles, hierarchy, and any available permissions)

2. A policy store in your system that defines who can access which resources

3. Retrieval-time enforcement that constrains search/RAG results to authorized resources only

Step 1: Define high-level access control rules

Start by defining the rules that govern which end users should have access to which Knowledge Base content ingested your product.

Key tasks:

1. User roles and groups (principals): Define how your product represents a user’s access (for example: department, role, team, project membership). Decide where this comes from, such as your product's existing RBAC system or an external identity provider.

2. Policy scope: Decide whether policies attach to. This will typically be

   • Containers (common for “space” or “teamspace” access)

   • Articles and Attachments (for exceptions or sensitive docs)

3. Inheritance rules: If a policy is set on a container, decide whether and how it inherits to child containers, articles, and attachments. This is typically required to keep ACL management scalable as hierarchies grow.

4. Granularity and sensitivity: If you need stricter controls, define sensitivity levels (for example: “Public,” “Internal,” “Confidential”) and how they interact with roles and groups. Decide whether “most restrictive wins” or “most specific wins” when rules conflict.

By the end of this step, you should have a clear answer to: “Given user X, which Containers, Articles, and Attachments can X read?”

Step 2: Enable metadata and tagging within your product

Even if the knowledge base system provides its own metadata, most products benefit from a standardized metadata schema that supports consistent policy enforcement and troubleshooting across integrations.

A practical approach is to store two distinct concepts:

1. Classification metadata (helps search UX and routing)

   1. Department or domain (HR, Legal, Engineering)

   2. Content type (Policy, Procedure, FAQ)

   3. Sensitivity label (Public, Internal, Confidential)

2. Authorization policy metadata (drives access control)

   1. Who can read the resource (roles, groups, users)

   2. Optional: explicit denies (if your policy model supports them)

Implementation tips:

1. Define a tagging strategy: Keep the set of tags/labels small and intentional. Prefer well-defined enums to free-form text to avoid drift.

2. Provide a policy and labeling interface: Let KB admins assign labels and access policies (single-item editing + bulk editing) across Containers, Articles, and Attachments.

3. Optional automated tagging: You can use NLP to suggest classification tags, but treat automated tags as suggestions unless your customer explicitly accepts automation.

4. Store policies in your own system: Persist policies keyed by Merge resource IDs so they remain consistent across Knowledge Base providers and do not depend on provider-specific permission APIs.

Step 3: Implement the custom authorization layer

This layer computes and enforces access based on your policies.

Core responsibilities:

1. Map principals to allowed scope: Given a user (and their roles/groups), determine the allowed set of Articles, Attachments, and Containers.

2. Represent inheritance efficiently: If Container policies inherit, compute effective access without repeatedly walking the full tree on every query.

3. 3. Make decisions explainable: Store or compute “why access was granted or denied” to support onboarding and troubleshooting.

Common authorization model:

• RBAC (role-based access control) is usually sufficient.

• The same structure can support ABAC (attribute-based access control) if you already have strong user attributes and need dynamic rules.

Step 4: Integrate authorization into Knowledge Base retrieval and response generation

Once the authorization layer is implemented, integrate it into your search and/or RAG pipeline.

Recommended flow:

1. Ingest content from Merge: Sync Containers, Articles, and Attachments, and store their hierarchy metadata.

2. Attach effective policy metadata: For each Container, Article, and Attachment, store the policy metadata you will use for filtering.

3. Pre-process each request: When a user submits a query:

   1. Resolve the user’s principals (roles/groups).

   2. Compute the user’s allowed scope (containers/articles).

4. Filter during retrieval (not after):

   1. Constrain keyword search and/or vector search to the allowed scope.

   2. Only retrieve authorized documents/chunks.

5. Generate access-controlled responses:

   1. Use only authorized context for the final answer.

   2. Do not include unauthorized citations, quotes, or snippets.

   3. If an agent takes follow-on actions (for example, “open full article” or "“download attachment”), authorize those fetches the same way.

Benefits of customer-managed ACLs (when you need them)

This advanced approach can be valuable when you need a policy model that is more consistent, operable, and explainable than mapping each KB system’s native permissions:

• Consistency across integrations: one policy scheme across different Knowledge Base sources, even when their permission models differ

• Simpler administration: customers manage access in one place (your product).

• Easier support: clear, explainable “why allowed or denied” behavior.

Conclusion

Customer-managed ACLs are an advanced approach that can improve consistency and operability for Enterprise Search and LLM-based experiences. By defining clear rules, implementing a standardized metadata and policy schema, and enforcing authorization at retrieval time, you can ensure end users only receive content they are permitted to access, even when source-system permission models are complex, inconsistent, or nonexistant.