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.

Cognee exposes several environment variables that let you harden a self-hosted deployment for production use. Some controls are enforced by default, while others remain permissive for local development, so you should review each setting before exposing Cognee to untrusted users or networks.

​
Security Controls

​
Require authentication for all API requests

ENABLE_BACKEND_ACCESS_CONTROL is the canonical posture switch; REQUIRE_AUTHENTICATION is an optional override on the auth requirement alone.
ENABLE_BACKEND_ACCESS_CONTROLREQUIRE_AUTHENTICATIONEffective behavior
true (default)unsetMulti-tenant mode: per-user/dataset isolated DBs and API endpoints require an authenticated user.
falseunsetSingle-user mode: shared DB and auth requirement off.
anytrueAuth is forced on (useful for a single-user deployment behind a shared token).
falsefalseAuth off.
truefalseMisconfiguration — multi-tenant mode always requires auth. Cognee logs a warning at startup and forces REQUIRE_AUTHENTICATION=true.
When neither variable is set, the default is multi-tenant mode with authentication required.
At startup, Cognee logs an auth posture: ... line summarizing the resolved decision and the reason (default, inherited from ENABLE_BACKEND_ACCESS_CONTROL, explicit REQUIRE_AUTHENTICATION, or forced on by multi-tenant mode). Use this log line to verify what is actually in effect after deployment.
If ENABLE_BACKEND_ACCESS_CONTROL=true (the default), authentication is enforced automatically regardless of the value of REQUIRE_AUTHENTICATION. Setting REQUIRE_AUTHENTICATION=false in this mode is ignored and a warning is logged at startup.

​
JWT token settings

FASTAPI_USERS_JWT_SECRET="super_secret"   # default — CHANGE IN PRODUCTION
JWT_LIFETIME_SECONDS=3600                 # default: 1 hour
FASTAPI_USERS_JWT_SECRET must be the same across all instances (e.g., all Kubernetes pods) so that a token issued by one pod is accepted by another. Use a long, randomly generated string in production and never commit the real value to version control.JWT_LIFETIME_SECONDS controls how long a bearer token or cookie remains valid before the user must log in again.

​
API Key Storage

HASH_API_KEY="False"   # default
When false, API keys are stored as plaintext in the relational database. When true, each key is hashed with SHA-256 before storage. The raw key is shown to the user only once at creation time and cannot be recovered afterward.
Migration note: Enabling HASH_API_KEY on a running system that already has plaintext API keys stored will break those existing keys immediately — the lookup hashes the incoming value and finds no match. You must either delete and re-issue all existing keys, or run a one-off migration to SHA-256-hash the existing api_key column values.

​
Local File System Access

ACCEPT_LOCAL_FILE_PATH=True   # default
When true, Cognee accepts local filesystem paths as data sources (e.g., /etc/passwd). This is convenient for local development but dangerous when Cognee is exposed as a multi-user backend — an authenticated user could read arbitrary files that the Cognee process has access to.Set to false when running Cognee as a backend service:
ACCEPT_LOCAL_FILE_PATH=False

​
Cypher Query Access

ALLOW_CYPHER_QUERY=True   # default
When true, users can execute raw Cypher queries against the graph database (SearchType.CYPHER) and use natural language-to-Cypher translation (SearchType.NATURAL_LANGUAGE). Disable this to limit users to higher-level semantic search only:
ALLOW_CYPHER_QUERY=False

​
Encrypting Neo4j Aura Credentials

When using the neo4j_aura_dev dataset database handler for multi-user mode, Cognee stores per-dataset Neo4j Aura database connection info in the relational database. The stored database password is encrypted with Fernet symmetric encryption; the encryption key is derived from NEO4J_ENCRYPTION_KEY:
NEO4J_ENCRYPTION_KEY="test_key"   # default — CHANGE IN PRODUCTION
The default value "test_key" is intentionally insecure. Replace it with a long random string in any environment that stores real Neo4j Aura credentials.
The Aura API credentials used to create or delete instances (NEO4J_CLIENT_ID, NEO4J_CLIENT_SECRET, and NEO4J_TENANT_ID) are read from environment variables when needed and are not stored in the relational database by this handler.

​
Dataset & Multi-User Isolation

ENABLE_BACKEND_ACCESS_CONTROL=True   # default
When enabled, Cognee creates isolated storage per user + dataset combination and enforces permission checks on every read and write operation. This is the primary control for preventing cross-tenant data leakage in multi-user deployments.Database support requirements:
LayerSupported backends
RelationalSQLite, PostgreSQL
VectorLanceDB, PGVector
GraphKuzu, Neo4j Aura (neo4j_aura_dev handler)
If you configure an unsupported backend (e.g., Qdrant, Weaviate), disable access control to avoid runtime errors:
ENABLE_BACKEND_ACCESS_CONTROL=False
Setting ENABLE_BACKEND_ACCESS_CONTROL=false alone also disables the auth requirement (single-user mode). You only need to add REQUIRE_AUTHENTICATION if you want to override that default — for example, REQUIRE_AUTHENTICATION=true to keep auth on for a single-user deployment behind a shared token.See Dataset Database Handlers for the full list of supported handlers.
When running Cognee locally for development or testing, you can disable authentication so that API calls succeed without a bearer token. Setting the single posture switch is enough:
ENABLE_BACKEND_ACCESS_CONTROL=false
With ENABLE_BACKEND_ACCESS_CONTROL=false and REQUIRE_AUTHENTICATION unset, REQUIRE_AUTHENTICATION inherits from the posture switch and the auth requirement is turned off automatically. (Previously, both variables had to be set to false independently; that is no longer required.)These values are read once when the server process starts, so you must restart the server after changing them. Check the auth posture: ... line in the startup logs to confirm the resolved decision.When authentication is disabled, unauthenticated requests are automatically served under a built-in default user (default_user@example.com). The relational database must be initialized before the first request so that this default user can be looked up or created.Troubleshooting 401 errors after setting the variables
SymptomCauseFix
Still getting 401 on all endpointsENABLE_BACKEND_ACCESS_CONTROL is still true, or REQUIRE_AUTHENTICATION=true is set explicitly and overrides itSet ENABLE_BACKEND_ACCESS_CONTROL=false and unset (or also set to false) REQUIRE_AUTHENTICATION
Startup log says auth was “forced on by multi-tenant mode”REQUIRE_AUTHENTICATION=false is combined with ENABLE_BACKEND_ACCESS_CONTROL=true — an unsafe combination that Cognee coerces to auth-onTo disable auth, also set ENABLE_BACKEND_ACCESS_CONTROL=false
401 persists after editing .envServer not restartedRestart the server — the variables are evaluated at import time
500 Failed to create default userRelational DB not initializedCall cognee.prune.prune_system() once, or let the server run its startup migrations before sending requests
Only use ENABLE_BACKEND_ACCESS_CONTROL=false in local or trusted environments unless you have another protection layer in place. It disables multi-user isolation, and it also disables the HTTP auth requirement unless you explicitly set REQUIRE_AUTHENTICATION=true.

Permissions Setup

Enable dataset isolation and access control

Multi-User Mode

Understand multi-tenant architecture