Dify knowledge base access permissions: who can see and use each document set
Access to a knowledge base is a design decision you make for each document set. Plan on the basis that no single platform-wide setting will protect every file in Dify, so the boundaries you draw in the knowledge base layer decide who can query what. A knowledge base is a collection of documents that Dify indexes for retrieval and attaches to apps, workflows and agents. Anyone who can use an app that draws on a knowledge base can receive answers built from its contents, so each knowledge base needs a named owner, a named audience and a scheduled review. Document that owner and audience pair before the first file is uploaded.
Separate knowledge bases make sense when two document sets have different audiences, retention rules or ingestion owners. For example (illustrative), board papers, HR case files and published policy pages rarely share a viewer group, so storing them together forces every reader of one set to be able to reach all of them. Your edition sets the outer boundary. The Community edition is limited to a single workspace, so everyone who can enter that workspace sits inside one permission domain. Multiple workspaces, SSO scopes for workspace access and web app access, and other administrative controls are listed for the Enterprise edition, as described in the Dify Enterprise SSO documentation. Confirm the exact role and knowledge base permission options in the version you run before you fix the layout.
Before loading documents, write down the decision for each set: which knowledge bases exist, who may open them, who may create or edit them, and which apps or API keys may read them. Creation rights and access are separate questions. A builder who makes an app may not need to read the documents it retrieves, and an integration that uploads files for indexing usually should not be able to query them. Automated ingestion is where keys tend to leak, so keep the key that writes documents apart from any key that serves answers. Check the Dify releases page and your version's notes to confirm whether a service API key can be bound to one knowledge base before you depend on that control.
Access options and when each fits
This table compares the four levers a team can use to control who reaches which knowledge base in self-hosted Dify. Read each row as a layer: a lever narrows access, but none of them stops a user who already holds the rights the lever grants. The main takeaway is that sensitive document sets need their own knowledge bases and scoped keys, and that workspace separation is the only lever that isolates tenants.
| Access option | When it fits | What it does not protect against |
|---|---|---|
| Single shared knowledge base per workspace | Documents that every member of the workspace may read, such as public product manuals or internal policies with no restricted tier | Any workspace member with knowledge base access can retrieve its contents through an app, so it is unsuitable for mixed sensitivity levels |
| Separate knowledge bases per sensitivity tier | Document sets with different audiences, such as HR records, legal matters or customer data, where each tier needs its own owners and app links | Mistakes in how apps are wired: an app connected to both a restricted and a general knowledge base still exposes the restricted content to its users |
| Scoped dataset API keys for the Knowledge API | Automated ingestion or retrieval by a back-end service that should only touch one knowledge base; confirm key binding and the 10-key workspace limit for your version | Leaked keys used within their scope, and users inside your own application who can query the knowledge base through it; keys belong on the server side |
| Workspace separation (Dify Enterprise multi-workspace) | Business units or customers that must be isolated from each other, with separate members, apps and knowledge bases | Access granted inside a workspace, so it does not separate roles within one team; the Community edition is limited to a single workspace |
| Creation rights versus access rights | Limiting who may create or delete knowledge bases while letting a wider group use apps that query them | Users who can edit an app or its prompts may still be able to change what it retrieves, so review editors separately from viewers |
Why sensitive document sets need their own knowledge bases
Dify knowledge base permissions control who can open a knowledge base, but they do not control what an app retrieves once it is connected to one. The reasons below all point the same way: keep sensitive documents in their own knowledge bases so that retrieval, deletion, API access and audit can each be scoped to that set alone.
Retrieval crosses connected knowledge bases
An app that is connected to several knowledge bases can return chunks from any of them when a question matches. A user who is allowed to use the app may therefore receive answers drawn from a document set they could never open directly. Before publishing, list every knowledge base each app connects to and confirm that the combination is one the data owner has approved. Test with questions that should only be answerable from the restricted set.
Deletion and re-indexing are per knowledge base
Removing a document, rebuilding an index or changing chunk settings happens inside one knowledge base at a time. If a sensitive set shares a knowledge base with ordinary content, a retention request or a correction forces work on the whole collection and risks affecting unrelated answers. A separate knowledge base lets the owner of the sensitive set delete or re-ingest its content on its own schedule and confirm the result without touching other sources.
API keys can be bound to one knowledge base
Automated ingestion through the Knowledge API can be scoped so that a key only writes to the knowledge base it was created for. Keeping sensitive sets separate means an ingestion pipeline for one team cannot read or overwrite another team's documents, even if its key is exposed. Confirm the binding behavior on your Dify version, since key scoping depends on the release you run, and store keys server side.
Audit and offboarding stay simple
When a person leaves a team or a contract ends, the access review for a dedicated knowledge base is short: one membership list, one set of API keys and one set of connected apps. Mixed collections make the same review slow and error-prone because every shared app and key must be traced back to the documents inside. Record the owner, the approved users and the connected apps for each sensitive knowledge base so that reviewers can confirm them later.
Exports omit chunk content
Dify app exports as YAML DSL files include app configuration, workflow nodes, prompts and knowledge base connections, but not the knowledge base content itself. Teams sometimes assume an export is a complete backup of an app, or a safe artifact to share between environments. It is neither. Restoring a sensitive app in another instance requires the knowledge base to be re-created and re-populated from its source, so plan that separately and include the knowledge base in your backup scope.
Separate owners for separate content
A knowledge base is a natural unit of ownership. When each sensitive set has a named owner who approves who may use it and which apps may connect to it, decisions about access stay with the people accountable for the data. Shared collections blur that line, and changes made for one group quietly affect another. Assign owners before the first document is uploaded and write down who may change connections.
How to set up scoped knowledge base access in Dify
This sequence separates who can create knowledge bases from who can use them, so each document class is retrieved only by the apps and people it was built for. It ends with a tested access map that you can rerun after changes.
Define document classes and owners
Your security or data owners group documents into classes by sensitivity and audience, such as public product material, internal policies, and customer or regulated records. For each class, they name one accountable owner who approves who may read the content and who may add or remove files. Record the classes and owners in a register that the platform team uses as the reference for every later step. Done when every planned document source appears in exactly one class and each owner has confirmed their class in writing.
Create one knowledge base per class
The platform team creates a separate knowledge base in Dify for each class, using names that match the register so that anyone reviewing the platform can trace content back to its owner. Keep sensitive material out of shared knowledge bases, because the separation you control in Dify is applied at the knowledge base level. Confirm the chunking and indexing settings for each knowledge base before loading documents, since some of these choices are difficult to reverse. Done when each class maps to one knowledge base and a test upload to the wrong knowledge base has been caught and removed.
Assign creation rights to a small group
Limit who can create knowledge bases and upload documents to a small group of named administrators or ingestion leads. Creation rights and access are separate: a person who can create a knowledge base is not automatically cleared to read every class, and most builders only need knowledge bases that are already connected to their apps. In the Community edition, all users share one workspace, so confirm what each role permits in your version. If you need hard separation between groups, the pricing page lists multiple workspaces as an Enterprise feature, so include it in your quote request. Done when a written list names who may create or edit each class.
Connect apps only to the knowledge bases each audience needs
Open each app and attach only the knowledge bases that its audience is cleared to use. A customer-facing assistant should not reference an internal policy knowledge base, because retrieval returns matching text to whoever asks the question. Record the connected sets for every app in the access map and review them after any change. Check: in the app's test conversation, ask a question whose answer exists only in a knowledge base the app is not connected to. The app should not return that content. Done when every app's connected sets match the access map.
Create dataset-scoped API keys for ingestion
Automate uploads through the Knowledge API with a key scoped to a single knowledge base, so a pipeline that loads one class cannot write to another. Dify's release notes indicate that binding keys to a specific knowledge base arrived in 1.17.1, so confirm that your version supports it before you rely on it. Store each key in your secrets manager, keep it on the server side, and rotate it when the owner of the pipeline changes. Check: send an upload with one key to a second knowledge base and confirm the request is refused. Done when each ingestion job has its own key and the cross-knowledge-base test fails as expected.
Verify access with test accounts
Create one test account for each audience, plus one account with no roles, and sign in to each in a separate private browser session. For every account, confirm which apps it can open, which knowledge bases it can see when it opens or edits an app, and what its test questions return. Record each result against the access map. If Enterprise SSO is in use, repeat the checks for both workspace access and web app access, because these are separate SSO scopes. Done when every result matches the map, and any mismatch has been fixed and retested.
Security and operational considerations for knowledge base access
Knowledge base permissions are only as strong as the platform underneath them. The controls below cover how secrets, session signing, outbound requests, encryption keys and role changes affect who can reach sensitive documents. Check each one in your own environment before loading restricted content.
Secret handling for API keys
Dataset-scoped and service API keys grant access to knowledge base content without a user session, so they need the same care as passwords. Store them in your secrets manager, keep them out of exported app DSL files and source repositories, and never place them in client-side code. Confirm who can view or create keys in each workspace and how keys are rotated when someone leaves the team.
SECRET_KEY and active sessions
The SECRET_KEY setting signs session cookies and JWTs and also encrypts OAuth credentials. Changing it after deployment logs out all users, so treat it as a controlled value: generate it once, store it in a vault, and plan the logout impact before any rotation. Confirm that the value is unique to each environment and never shared between staging and production.
Outbound requests through the SSRF proxy
Knowledge base imports, website crawls and tool calls can make outbound requests from the Dify server. The SSRF_PROXY settings route these requests through a proxy that blocks internal and private IP ranges, which limits how a misconfigured or malicious source can reach your internal services. Verify that the proxy is active in your deployment and test that a crawl pointed at an internal address is refused.
Workspace encryption key separation
Workspace encryption keys can be stored locally or in Azure Key Vault. Where documents are sensitive, decide whether the key store must sit outside the application host and who administers it, because a key held on the same server as the data offers less separation. Record which key store protects each workspace, and confirm that key custody is covered by your backup and recovery plan.
Access review after role changes
Knowledge base access changes when a person moves teams, leaves, or gains a new role, but permissions and API keys often stay in place. Set a recurring review of workspace members, knowledge base permissions and API keys bound to each knowledge base. Compare the list against your identity provider, and remove access that no longer matches a documented owner.
Upgrade and key review checkpoints
Security settings and sandbox behavior change between releases, so each upgrade is a point to recheck access controls. Review the release notes for security changes, check .env.example for new variables, and back up before upgrading. Confirm after each upgrade that existing API keys, knowledge base permissions and proxy settings still behave as you documented.
Questions teams ask before scoping knowledge base access
How much effort does a scoped knowledge base access design take?
The effort depends mostly on how many distinct document audiences exist and how many sensitive document sets need their own knowledge base. A design for one workspace with a single audience is a short exercise, while a design that separates HR, legal, finance and customer records into separate knowledge bases, each with its own API keys and test users, takes considerably longer. The main drivers are the number of audiences, the number of classification levels, whether existing sharing practices must be mapped, and how many knowledge bases already exist in the workspace. Ask any provider for a written scope that lists each audience, each knowledge base and each key before agreeing to a figure.
Can our team scope Dify knowledge base access without outside help?
Yes, a capable internal team can do this work, provided it has someone who understands both the Dify console and the organization's data classification. The Dify roles and knowledge base settings are documented in the Dify app management docs, and the design itself is mostly decisions about grouping, ownership and key handling. Outside help usually adds value in reviewing the design against your policies, testing permission boundaries with real accounts, and documenting the result so an auditor can follow it. Teams without a security engineer or a Dify administrator often find the testing and documentation steps take the most time.
What does the work need from our organization?
The work needs named owners, a document classification scheme and a set of test users before design starts. Each knowledge base should have an accountable business owner who approves who may read it and who may create or change it. Classification tells the design which documents must be isolated, for example by labeling content as public, internal, confidential or restricted. Test users are accounts from each intended audience plus at least one account that should be denied, so the team can prove both sides of the boundary. Without these inputs, the design stalls at the point where it has to choose who decides.
How long does a scoped access project run?
There is no fixed duration, because the timeline follows document volume and the number of audiences. A workspace with a small number of knowledge bases and clear owners can be designed and tested quickly, while a large estate with many departments, inconsistent document ownership and external users needs more discovery and more rounds of testing. Ask for a timeline tied to a written list of knowledge bases, audiences and test cases, and check which dependencies, such as owner sign-off or classification decisions, sit outside the provider's control.
Can Community edition separate knowledge base access by workspace?
The Community edition is limited to a single workspace according to the Dify pricing page, so it cannot use multiple workspaces as a separation boundary. Within that single workspace, separation has to rely on how knowledge bases, members and API keys are organized, which is a weaker control for sensitive document sets. Multiple workspaces, SSO and advanced security are listed as Enterprise edition features, so an organization that needs hard separation between audiences should confirm the edition and licensing terms before choosing a design. The Dify Open Source License also restricts multi-tenant operation without written authorization, which matters if the deployment will serve several separate organizations.
What can an audit of our Dify access design prove, and what can it not?
An audit can check whether the documented access design exists, whether it matches the configuration in the console, whether owners approved access, and whether tests showed that unauthorized accounts were denied. It cannot prove that no document was ever exposed outside the design, because that depends on logs, retention and behavior the design did not capture. Audits also cannot confirm controls that were never configured or tested. DeployOpen prepares systems, controls and evidence for compliance assessments but does not issue audit reports or certifications; independent auditors and certification bodies do that work. Ask your auditor which evidence formats they accept before the design is finalized.
Which API key settings should we confirm before relying on scoped keys?
Confirm that each key is bound to the knowledge base it serves, that keys are stored server side, and that the workspace key limit fits your plan. The Dify knowledge API and dataset-scoped key behavior are described in the Dify documentation, and the version that introduced binding keys to specific knowledge bases should be checked against your deployed release on the Dify releases page. Test each key against a knowledge base it should not reach, record the denial, and rotate keys through a documented process. Keys that are shared across audiences defeat the separation the knowledge base design is meant to create.
How DeployOpen scopes and delivers knowledge base access controls
Access control for Dify knowledge bases is delivered under a written, fixed scope agreed before any work starts. The scope names every knowledge base in the workspace, the roles and workspace members who may create, edit, or use each one, the dataset-scoped API keys that automation will hold, and the test cases that prove each rule holds. Because the scope lists the knowledge bases by name, the sensitive document sets are identified up front and given their own knowledge bases rather than being mixed into a shared one. A quote follows from that written scope, so the scope is the place to decide how many knowledge bases, roles and keys the engagement covers.
Delivery happens inside your own infrastructure, whether that is your cloud accounts, data centers or an air-gapped network, so the workspace, its metadata database and its vector store stay under your control throughout. DeployOpen configures the roles and knowledge base permissions in the Dify console, issues the scoped keys, and then verifies each rule with test accounts that represent the real personas in your organization, such as a contributor who can create a knowledge base but cannot read another team's documents. Each test case in the scope has an expected result and a recorded outcome, so you receive evidence of what was checked. DeployOpen prepares these systems, controls and records for your own compliance assessments, but it does not issue audit reports or certifications; independent auditors and certification bodies do that work.
Access rules change as Dify changes, so the scope should also say whether ongoing work is included. Dify ships minor releases roughly monthly, and each upgrade can affect permission behavior, so you should confirm with DeployOpen whether re-running the access test cases after an upgrade is part of the fixed scope or sits under an optional retainer for upgrades and continuous testing. Ask for the retainer terms in writing, including how often the test cases are rerun and who reviews changes to roles, members and keys. Keeping the test cases as a versioned artifact in your own repository makes that handover straightforward whichever option you choose.
