Skip to main content
Enable Cognee’s permission system for data isolation and access control. For detailed concepts, see Cognee Permissions System.

​
Enable Permission System

Set the environment variable to enable access control: 
ENABLE_BACKEND_ACCESS_CONTROL=true # this is set to true by default
REQUIRE_AUTHENTICATION=true

​
Auto-enable behavior

When ENABLE_BACKEND_ACCESS_CONTROL is not explicitly set, Cognee automatically enables multi-user mode if the configured graph and vector setup passes the runtime compatibility checks. At a high level, that means both of the following must be true:
  • The configured graph dataset handler is supported and matches the selected graph provider.
  • The configured vector dataset handler is supported and matches the selected vector provider.
Set ENABLE_BACKEND_ACCESS_CONTROL=false to keep single-user mode regardless of which databases are configured. For the supported backend combinations and handler details, see Security & Privacy and Dataset Database Handlers.

​
Dataset Queue

When backend access control is enabled, Cognee can limit the number of dataset-level operations that run concurrently. This caps overall concurrent dataset work and can reduce contention when many tasks access datasets at the same time. The queue is enabled by default and is automatically disabled when ENABLE_BACKEND_ACCESS_CONTROL=false. 
# Maximum concurrent dataset slots (default: 128, matching DATABASE_MAX_LRU_CACHE_SIZE)
DATASET_QUEUE_MAX_CONCURRENT=10
When the limit is reached, additional dataset operations wait until a slot is freed. Enabling the queue trades some parallel throughput for consistency on concurrent workloads with many datasets.

​
Subprocess engine teardown coordination

When subprocess-mode databases are in use (graph_database_subprocess_enabled=true or vector_db_subprocess_enabled=true), the queue also coordinates eviction of the cached per-dataset engine on dataset-context exit. The teardown only runs once the exiting task is the last holder of that dataset’s queue slot — so an in-flight task that still has the dataset open will not observe a torn-down engine. If you set DATASET_QUEUE_ENABLED=false while leaving subprocess mode on, this teardown becomes a no-op: subprocess engines will not be evicted or closed when a dataset context exits, and the database file’s flock() will remain held until the cached engine is closed or evicted, or until the worker process shuts down. Keep the queue enabled when running with subprocess databases under concurrent multi-dataset workloads.
If you call set_database_global_context_variables() directly in custom pipelines, prefer the async with form over await. The await form is deprecated and will emit a DeprecationWarning:

​
Database Setup

Choose your relational database:
  • SQLite — Local development (auto-creates files)
  • Postgres — Production (requires manual setup)
See Relational Databases for detailed configuration.

​
Authentication

​
API Server

Start the server with authentication: 
uvicorn cognee.api.client:app --host 0.0.0.0 --port 8000
Default credentials (development only):

​
Programmatic Access

See Permission Snippets for complete programmatic examples.

​
Data Organization

Data is automatically organized by user and dataset. Each user gets isolated storage: 
.cognee_system/databases/<user_uuid>/
├── <dataset_uuid>.pkl         # Kùzu graph database
└── <dataset_uuid>.lance.db/   # LanceDB vector database

​
Troubleshooting

If a request fails with a permission error:
  • Confirm the request is authenticated as the expected user.
  • Confirm the target dataset belongs to that user, or has been shared with them.
  • If you are testing locally, verify REQUIRE_AUTHENTICATION=true and ENABLE_BACKEND_ACCESS_CONTROL=true match the mode you expect.
For complete authenticated request examples, see Permission Snippets.
With access control enabled, Cognee stores graph and vector data per user and per dataset. If data appears to leak across users or is missing unexpectedly:
  • Verify ENABLE_BACKEND_ACCESS_CONTROL=true.
  • Verify you are reading and writing as the intended authenticated user.
  • Check that separate user-specific database files exist on disk:
ls -la .cognee_system/databases/<user_uuid>/
Different users should have different database paths and dataset files.
Symptom: Cognee raises an EnvironmentError about a graph provider/handler mismatch when GRAPH_DATABASE_PROVIDER=neo4j and ENABLE_BACKEND_ACCESS_CONTROL=true.Root cause: Self-hosted (local) Neo4j is not supported for multi-user mode. In Cognee’s runtime checks, direct graph-provider support for multi-user mode is limited to kuzu and falkor (GRAPH_DBS_WITH_MULTI_USER_SUPPORT). Neo4j is only supported in multi-user mode through the neo4j_aura_dev dataset handler, so enabling ENABLE_BACKEND_ACCESS_CONTROL=true with a self-hosted Neo4j setup leads to this error.
Recommended for self-hosted Neo4j deployments:
GRAPH_DATABASE_PROVIDER=neo4j
GRAPH_DATABASE_URL=bolt://localhost:7687
GRAPH_DATABASE_USERNAME=neo4j
GRAPH_DATABASE_PASSWORD=yourpassword
ENABLE_BACKEND_ACCESS_CONTROL=false

Permission System

Learn about users, tenants, roles, and ACL

Usage Guide

How to use permission features