Security & Privacy

Authentication

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_CONTROL`	`REQUIRE_AUTHENTICATION`	Effective behavior
`true` (default)	unset	Multi-tenant mode: per-user/dataset isolated DBs and API endpoints require an authenticated user.
`false`	unset	Single-user mode: shared DB and auth requirement off.
any	`true`	Auth is forced on (useful for a single-user deployment behind a shared token).
`false`	`false`	Auth off.
`true`	`false`	Misconfiguration — 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.

Default user credentials

When an operation runs without an explicit authenticated user, Cognee falls back to a built-in default user — created on first use as a superuser. This happens for SDK/library calls, and for HTTP requests when authentication is off (single-user mode). Override its credentials with:

DEFAULT_USER_EMAIL="default_user@example.com"   # default
DEFAULT_USER_PASSWORD="default_password"         # default

When ENABLE_BACKEND_ACCESS_CONTROL=true, HTTP endpoints require an authenticated user, so the default user is not used to serve unauthenticated requests — but SDK calls still fall back to it. Set DEFAULT_USER_EMAIL and DEFAULT_USER_PASSWORD before the default user is first created to give this auto-created superuser known credentials you can then log in with. Changing these values later does not update an existing user; update or recreate that user separately, then restart the process so Cognee reads the new environment. See Users for the full permission model.

Data Protection

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

The flag governs file:// URIs and path strings that resolve to an existing local file; those inputs raise IngestionError: Local files are not accepted. when it is disabled. It is not a filter on submitted text: an absolute-looking string that does not point to an existing file is ingested as text content either way, since Cognee never treats it as a path.

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

Outbound HTTP Requests (SSRF Protection)

ALLOW_HTTP_REQUESTS=True   # default

When Cognee ingests an http(s) URL (via add() → save_data_item_to_storage) or crawls a page, it fetches that URL server-side. To prevent Server-Side Request Forgery (SSRF, CWE-918), every user-supplied outbound URL is now validated before any request is made.ALLOW_HTTP_REQUESTS (default true) gates outbound HTTP(S) fetching. Set it to false to disable all remote URL ingestion — any http(s) URL is then rejected:

ALLOW_HTTP_REQUESTS=False

Falsey values are false, 0, no, and off (case-insensitive); any other value leaves outbound fetching enabled.When outbound requests are allowed, each URL still passes through these checks before it is fetched:

Scheme — only http and https are permitted. Other schemes (e.g. ftp://, gopher://) are rejected.
Host — the URL must contain a host, and that host must resolve. Hostless or unresolvable URLs are rejected.
Resolved address — the host is resolved and every resolved IP is checked. The request is blocked if any address is loopback, private, link-local, reserved, multicast, unspecified, or IPv6 site-local. This blocks internal and cloud-metadata targets such as 127.0.0.1, ::1, 169.254.169.254, 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. IP-literal URLs (e.g. http://[::1]) are validated directly, so DNS-rebinding and IP-literal bypasses are also caught.

To keep public URLs from redirecting the server to an internal address, the crawler’s HTTP client runs with follow_redirects=False — redirects are not followed automatically.

A blocked or disabled request raises SSRFProtectionError (an HTTP 403 CogneeValidationError) instead of silently fetching the internal target. If you see this during ingestion, check that the URL is a public http(s) address that resolves to a routable IP, and that ALLOW_HTTP_REQUESTS is not set to false.

Encrypting Neo4j Credentials

When using the neo4j_aura_dev or neo4j_community dataset database handler for multi-user mode, Cognee stores per-dataset Neo4j connection info in the relational database — for neo4j_aura_dev the provisioned Aura instance, for neo4j_community the per-dataset Docker container. The stored database password is encrypted with Fernet symmetric encryption; both handlers derive the encryption key from the same 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 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.

Encrypting Integration Credentials

Third-party OAuth integrations (Slack, GitHub, and Linear) store their tokens in the relational integration_credentials table. The token payload is encrypted with AES-256-GCM under a fresh random 96-bit nonce per write; only non-secret metadata — the workspace label, Slack team and enterprise ids, the bot and installing member’s user ids, the granted OAuth scopes, and the allowed-channel list — is stored in the clear.Keys are configured as a keyring — a set of 32-byte keys, each addressed by a short key id — so that keys can be rotated without re-encrypting existing rows:

INTEGRATION_CREDENTIALS_KEYS='{"1": "<base64-encoded 32-byte key>"}'
INTEGRATION_CREDENTIALS_ACTIVE_KEY_ID="1"   # default

Variable	Meaning
`INTEGRATION_CREDENTIALS_KEYS`	JSON object of every currently decryptable key, `{"<key_id>": "<base64 key>"}`. Preferred.
`INTEGRATION_CREDENTIALS_ACTIVE_KEY_ID`	The key id new rows are written under; it must exist in the ring. Defaults to `"1"`.
`INTEGRATION_CREDENTIALS_KEY`	Legacy single-key fallback, used only when `INTEGRATION_CREDENTIALS_KEYS` is unset. Loaded into the ring under id `"1"`.

There is no default key and no derived fallback: if neither variable is set, or a key does not decode to exactly 32 bytes, credential writes fail with a RuntimeError rather than producing ciphertext nobody can decrypt later. Generate a key with:

python -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

Rotation. Add the new key to INTEGRATION_CREDENTIALS_KEYS alongside the old one under a new id, then point INTEGRATION_CREDENTIALS_ACTIVE_KEY_ID at it. Every row records the key id it was written with, so existing rows keep decrypting under their original key; reconnecting an integration rewrites its row under the active key. Remove an old key from the ring only once no row still references it.Revocation. Disconnecting an integration marks the stored credential revoked and makes a best-effort call to the provider’s revoke endpoint. Provider-side removal has the same effect: for Slack, an app_uninstalled or tokens_revoked event deactivates the stored installation, so no usable token survives an uninstall.

Multi-User Isolation

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:

Layer	Supported backends
Relational	SQLite, PostgreSQL
Vector	LanceDB, PGVector
Graph	Kuzu, 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.

Disabling Authentication for Local Development

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

Symptom	Cause	Fix
Still getting `401` on all endpoints	`ENABLE_BACKEND_ACCESS_CONTROL` is still `true`, or `REQUIRE_AUTHENTICATION=true` is set explicitly and overrides it	Set `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-on	To disable auth, also set `ENABLE_BACKEND_ACCESS_CONTROL=false`
`401` persists after editing `.env`	Server not restarted	Restart the server — the variables are evaluated at import time
`500 Failed to create default user`	Relational DB not initialized	Call `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.

Recommended Production Settings

# Authentication
REQUIRE_AUTHENTICATION=True
FASTAPI_USERS_JWT_SECRET="<random-64-char-string>"
JWT_LIFETIME_SECONDS=3600

# API key security
HASH_API_KEY=True

# Multi-user isolation
ENABLE_BACKEND_ACCESS_CONTROL=True

# Prevent arbitrary file reads (set False for backend deployments)
ACCEPT_LOCAL_FILE_PATH=False

# Limit direct graph queries (optional — set False to restrict to semantic search)
ALLOW_CYPHER_QUERY=False

# Outbound URL ingestion is validated against SSRF; set False to disable remote fetches entirely
ALLOW_HTTP_REQUESTS=True

# Neo4j credential encryption (only required when using the neo4j_aura_dev or neo4j_community handler)
NEO4J_ENCRYPTION_KEY="<random-64-char-string>"

For detailed instructions on the multi-user permission system (users, tenants, roles, and ACL), see Cognee Permissions System.

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Rust SDK

TypeScript SDK

OSS

Security Controls

Require authentication for all API requests

JWT token settings

Default user credentials

API Key Storage

Local File System Access

Cypher Query Access

Outbound HTTP Requests (SSRF Protection)

Encrypting Neo4j Credentials

Encrypting Integration Credentials

Dataset & Multi-User Isolation

Recommended Production Settings

Permissions Setup

Multi-User Mode

​Security Controls

​Require authentication for all API requests

​JWT token settings

​Default user credentials

​API Key Storage

​Local File System Access

​Cypher Query Access

​Outbound HTTP Requests (SSRF Protection)

​Encrypting Neo4j Credentials

​Encrypting Integration Credentials

​Dataset & Multi-User Isolation

​Recommended Production Settings

Permissions Setup

Multi-User Mode

Security Controls

Require authentication for all API requests

JWT token settings

Default user credentials

API Key Storage

Local File System Access

Cypher Query Access

Outbound HTTP Requests (SSRF Protection)

Encrypting Neo4j Credentials

Encrypting Integration Credentials

Dataset & Multi-User Isolation

Recommended Production Settings