Skip to main content

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.

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.

​
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):
  • Username: default_user@example.com
  • Password: default_password

​
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