Cognee Multi-Tenant Permissions System
Overview
Cogneeβs permissions system provides multi-tenant isolation. This feature enables complete separation of data contexts, ensuring that each tenant, project, or customer has isolated access to their data with no leakage between contexts.
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
To enable the permissions system, set the following environment variable:
ENABLE_BACKEND_ACCESS_CONTROL=True
Important: When this is enabled, Cognee will:
- 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
This approach ensures that each user and dataset combination gets completely separate database instances, preventing any possibility of data leakage between contexts.
Core Concepts
Permission Hierarchy
Tenant
βββ Users (belong to tenant)
βββ Roles (defined within tenant)
βββ Datasets
βββ Data (documents/files)
βββ Permissions (read, write, delete, share)
Tenants
Multi-tenant isolation containers that:
- Group users and roles together
- Provide organizational boundaries
- Enable hierarchical permission management
Users
Individual system users who can:
- 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
Permission groupings within tenants that:
- Can be assigned to multiple users
- Simplify permission management at scale
- Inherit tenant-level defaults
Datasets
Data containers that:
- 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
The system creates separate database directories for each user-dataset combination:
.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
Four types of permissions available:
- 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
- Dataset Creation: When a user creates a dataset, they automatically receive all permissions (read, write, delete, share)
- Permission Sharing: Only users with βshareβ permission can grant permissions to others
- Access Control: All operations check permissions before execution
- Inheritance: Users can inherit permissions through roles and tenant
Access Control Logic
The system enforces permissions at multiple levels:
- Search Operations: Users can only search datasets they have βreadβ permission for
- Data Addition: Requires βwriteβ permission on the target dataset
- Data Deletion: Requires βdeleteβ permission on the specific documents
- Permission Sharing: Requires βshareβ permission on the dataset
ACL (Access Control List) Structure
Permissions are managed through a relational database with the following key tables:
- 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
NOTE: All endpoints are available via Swagger documentation at localhost:8000/docs
when running the Cognee backend.
Join the Conversation!
Have questions about creating custom tasks? Join our community to discuss implementation strategies and best practices!