​

Cognee Multi-Tenant Permissions System

​

Overview

​

Key Features

• Complete Data Isolation: Each context gets separate graph and vector stores
• Dataset-Level Permissions: Fine-grained control over data access (read, write, delete, share)
• Multi-Tenant Architecture: Support for tenants, roles, and users with hierarchical permissions
• File-Based Database Isolation: Uses Kuzu (graph database) and LanceDB (vector database) for complete separation

​

Configuration

ENABLE_BACKEND_ACCESS_CONTROL=True

• Ignore user-configured graph and vector database settings
• Enforce the use of Kuzu (file-based graph db) and LanceDB (file-based vector db)
• Deploy completely separate database instances per user per dataset

​

Core Concepts

​

Permission Hierarchy

Tenant
├── Users (belong to tenant)
├── Roles (defined within tenant)
└── Datasets
    ├── Data (documents/files)
    └── Permissions (read, write, delete, share)

​

Tenants

• Group users and roles together
• Provide organizational boundaries
• Enable hierarchical permission management

​

Users

• Belong to a tenant (or operate without a tenant)
• Have roles assigned within their tenant
• Own and access datasets based on permissions
• Be granted direct permissions on specific datasets

​

Roles

• Can be assigned to multiple users
• Simplify permission management at scale
• Inherit tenant-level defaults

​

Datasets

• Hold one or multiple documents/files
• Have separate graph and vector stores per user
• Support fine-grained permissions
• Maintain complete isolation between users

Database Isolation Mechanism

.cognee_system/
├── databases/
│   ├── user_1/
│   │   ├── dataset_a/
│   │   │   ├── kuzu_graph/
│   │   │   └── lancedb_vectors/
│   │   └── dataset_b/
│   │       ├── kuzu_graph/
│   │       └── lancedb_vectors/
│   └── user_2/
│       └── dataset_a/
│           ├── kuzu_graph/
│           └── lancedb_vectors/

​

Permissions

• read: View and search dataset contents
• write: Add new data to the dataset
• delete: Remove documents from the dataset
• share: Grant permissions to other users

​

Permission Management

​

Permission Assignment Rules

1. Dataset Creation: When a user creates a dataset, they automatically receive all permissions (read, write, delete, share)
2. Permission Sharing: Only users with ‘share’ permission can grant permissions to others
3. Access Control: All operations check permissions before execution
4. Inheritance: Users can inherit permissions through roles and tenant

​

Access Control Logic

1. Search Operations: Users can only search datasets they have ‘read’ permission for
2. Data Addition: Requires ‘write’ permission on the target dataset
3. Data Deletion: Requires ‘delete’ permission on the specific documents
4. Permission Sharing: Requires ‘share’ permission on the dataset

ACL (Access Control List) Structure

• principals: Base table for users, roles, and tenants
• permissions: Defines available permission types (read, write, delete, share)
• acls: Maps principals to data with specific permissions
• dataset: Represents a group of documents/files (has links to the Data table for this information) with associated permissions

​

Let’s take a quick look

​

1. First things first, run cognee backend.

• If you haven’t done yet, clone cognee and navigate to the root
  Copy

  Ask AI

  git clone https://github.com/topoteretes/cognee.git
  
  cd cognee
  

• Creave venv and install dependencies
  Copy

  Ask AI

  uv venv
  source .venv/bin/activate
  
  uv pip install -r pyproject.toml
  

• Run cognee backend
  Copy

  Ask AI

  uvicorn cognee.api.client:app --host 0.0.0.0 --port 8000 --reload
  

​

2. Navigate to Swagger docs

1. Before trying any endpoints, you need to login first. Login as the default user
2. Add a new dataset and note the dataset ID
3. “Cognify” to build a knowledge graph from the uploaded data
4. Search the freshly generated dataset – everything works for the default user
5. Register a second user in the system
6. Verify that the second user now appears in the user table and note the ID (We will need it while giving the permissions) You can access the user table from your cognee_db depending on which relational database (SQLite or Postgres) you used in the .env file. Below is the SQLite example. The path to the database is /path-to-your-cognee/cognee/.cognee_system/databases/cognee_db
7. Log in with the second user’s credentials
8. Second user tries to run “cognify” on the dataset that we just added (and noted the ID) but fails due to missing “write” permissions
9. Second user attempts to give permission to themselves but is blocked as well because they don’t have the “share” permission. Notice principal_id is the ID that is automatically created when we registered the second user. You should get it from the users table in cognee_db. In the request body, we’ll use the dataset ID that we saved in the first step.
10. Login as the default user again and grant the write permission to the second user.
11. With write permission, the second user can run “Cognify” successfully.
12. The default user also grants read permission to the second user.
13. Now the second user can search the dataset without restrictions.

​

Join the Conversation!