> ## 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 **disabled by default** and is automatically disabled when `ENABLE_BACKEND_ACCESS_CONTROL=false`.

```dotenv theme={null}
# Enable the dataset queue
DATASET_QUEUE_ENABLED=true

# 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.

<Warning>
  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`:

  ```python theme={null}
  # Deprecated — slot is released only when the current asyncio task ends
  await set_database_global_context_variables(dataset_id, user_id)

  # Preferred — slot is released automatically when the block exits
  async with set_database_global_context_variables(dataset_id, user_id):
      ...
  ```
</Warning>

## 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/<user_uuid>/
├── <dataset_uuid>.pkl         # Kùzu graph database
└── <dataset_uuid>.lance.db/   # LanceDB vector database
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Permission denied">
    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).
  </Accordion>

  <Accordion title="Data isolation">
    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/<user_uuid>/
    ```

    Different users should have different database paths and dataset files.
  </Accordion>

  <Accordion title="401/403 on add or search">
    When access control is enabled, `VECTOR_DB_PROVIDER` and `VECTOR_DATASET_DATABASE_HANDLER` must match. If you set `VECTOR_DB_PROVIDER=pgvector` but leave the handler at the default `lancedb`, all API requests fail with auth errors.

    | Vector provider     | Required handler env var                            |
    | ------------------- | --------------------------------------------------- |
    | `lancedb` (default) | `VECTOR_DATASET_DATABASE_HANDLER=lancedb` (default) |
    | `pgvector`          | `VECTOR_DATASET_DATABASE_HANDLER=pgvector`          |

    Example — using PGVector with access control:

    ```dotenv theme={null}
    VECTOR_DB_PROVIDER=pgvector
    VECTOR_DATASET_DATABASE_HANDLER=pgvector
    VECTOR_DB_URL=postgresql://user:pass@localhost:5432/cognee_db
    ```
  </Accordion>

  <Accordion title="Local Neo4j + multi-user mode: provider/handler mismatch error">
    **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.

    <Tabs>
      <Tab title="Single-User Local Neo4j">
        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
        ```
      </Tab>

      <Tab title="Multi-User with Neo4j Aura">
        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=<your_oauth_client_id>
        NEO4J_CLIENT_SECRET=<your_oauth_client_secret>
        NEO4J_TENANT_ID=<your_aura_tenant_id>
        NEO4J_ENCRYPTION_KEY=<a_strong_random_key>
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

<Columns cols={2}>
  <Card title="Permission System" icon="brain" href="/core-concepts/multi-user-mode/permissions-system/overview">
    Learn about users, tenants, roles, and ACL
  </Card>

  <Card title="Usage Guide" icon="book-open" href="/guides/permission-snippets">
    How to use permission features
  </Card>
</Columns>