> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt > Use this file to discover all available pages before exploring further. # Permissions Setup > Configure Cognee's permission system and access control Enable Cognee's permission system for data isolation and access control. For detailed concepts, see [Cognee Permissions System](/core-concepts/multi-user-mode/permissions-system/overview). ## Enable Permission System Set the environment variable to enable access control: ```dotenv theme={null} 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](/setup-configuration/security) and [Dataset Database Handlers](/core-concepts/multi-user-mode/dataset-database-handlers/dataset-database-handlers-what-are-they). ## 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`. ```dotenv theme={null} # 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. ### Engine cache pinning Cognee caches per-dataset graph and vector engines in a fixed-size LRU cache sized by `DATABASE_MAX_LRU_CACHE_SIZE`. While a dataset holds a queue slot, its graph and vector engines are **pinned** and are not evicted by capacity pressure — even if they are the least-recently-used entries. This prevents a dataset that an admitted pipeline is still using (for example, one idling on an LLM call mid-`cognify`) from having its engine closed underneath it, which was a source of DB lock and cache-overflow errors. As a result, when every cached entry is pinned, the engine cache can briefly exceed `DATABASE_MAX_LRU_CACHE_SIZE`. This overflow is bounded by `DATASET_QUEUE_MAX_CONCURRENT` (no more datasets than the queue admits can be pinned at once). When the queue is disabled (`DATASET_QUEUE_ENABLED=false`, or `ENABLE_BACKEND_ACCESS_CONTROL=false`), nothing is pinned and eviction falls back to plain least-recently-used recency. ### 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. ## Database Setup Choose your relational database: * **SQLite** — Local development (auto-creates files) * **Postgres** — Production (requires manual setup) See [Relational Databases](./relational-databases) for detailed configuration. ## Authentication ### API Server Start the server with authentication: ```bash theme={null} uvicorn cognee.api.client:app --host 0.0.0.0 --port 8000 ``` **Default credentials (development only):** * Username: `default_user@example.com` * Password: `default_password` ### Programmatic Access See [Permission Snippets](/guides/permission-snippets) for complete programmatic examples. ## Data Organization Data is automatically organized by user and dataset. Each user gets isolated storage: ``` .cognee_system/databases// ├── .pkl # Kùzu graph database └── .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](/guides/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: ```bash theme={null} ls -la .cognee_system/databases// ``` Different users should have different database paths and dataset files. When access control is enabled, `VECTOR_DB_PROVIDER` and `VECTOR_DATASET_DATABASE_HANDLER` must resolve to a compatible pair. For the built-in providers below, leaving the handler at its default lets Cognee auto-select the matching handler. Requests fail when you explicitly choose an incompatible handler. | Vector provider | Resolved handler in access-control mode | Do you need to set `VECTOR_DATASET_DATABASE_HANDLER`? | | ------------------- | --------------------------------------- | ----------------------------------------------------- | | `lancedb` (default) | `lancedb` | No | | `pgvector` | `pgvector` | No, unless you want to set it explicitly | | `turso` | `turso` | No, unless you want to set it explicitly | Example — using PGVector with access control: ```dotenv theme={null} VECTOR_DB_PROVIDER=pgvector # Optional: Cognee resolves this to pgvector automatically when omitted. VECTOR_DATASET_DATABASE_HANDLER=pgvector VECTOR_DB_URL=postgresql://user:pass@localhost:5432/cognee_db ``` **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: ```dotenv theme={null} GRAPH_DATABASE_PROVIDER=neo4j GRAPH_DATABASE_URL=bolt://localhost:7687 GRAPH_DATABASE_USERNAME=neo4j GRAPH_DATABASE_PASSWORD=yourpassword ENABLE_BACKEND_ACCESS_CONTROL=false ``` Use [Neo4j Aura with the `neo4j_aura_dev` handler](/core-concepts/multi-user-mode/dataset-database-handlers/existing-dataset-database-handlers/neo4j-aura-dev). This is the only supported path for Neo4j in multi-user deployments: ```dotenv theme={null} GRAPH_DATABASE_PROVIDER=neo4j GRAPH_DATASET_DATABASE_HANDLER=neo4j_aura_dev NEO4J_CLIENT_ID= NEO4J_CLIENT_SECRET= NEO4J_TENANT_ID= NEO4J_ENCRYPTION_KEY= ``` Learn about users, tenants, roles, and ACL How to use permission features