This guide demonstrates how to use multi-tenant features in Cognee through practical examples. Before you start:

​
Example: Sharing a Dataset Between Users

This example shows how to create a dataset, add data, and share it with another user.

​
Step 1: Start the API Server

uvicorn cognee.api.client:app --host 0.0.0.0 --port 8000

​
Step 2: Login as First User

# Login and get access token
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=default_user@example.com&password=default_password"

# Store token for convenience
TOKEN1="$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=default_user@example.com&password=default_password' | jq -r .access_token)"

​
Step 3: Create a Dataset

curl -X POST "http://localhost:8000/api/v1/datasets" \
  -H "Authorization: Bearer $TOKEN1" \
  -H "Content-Type: application/json" \
  -d '{"name": "shared_docs"}'
Response: {"id": "dataset-uuid-123", "name": "shared_docs", "owner_id": "user-uuid-456", ...}

​
Step 4: Add Data to Dataset

curl -X POST "http://localhost:8000/api/v1/add" \
  -H "Authorization: Bearer $TOKEN1" \
  -F "datasetName=shared_docs" \
  -F "data=@/path/to/document.pdf"

​
Step 5: Search Your Dataset

curl -X POST "http://localhost:8000/api/v1/search" \
  -H "Authorization: Bearer $TOKEN1" \
  -H "Content-Type: application/json" \
  -d '{
        "search_type": "GRAPH_COMPLETION",
        "query": "What is this document about?",
        "dataset_ids": ["dataset-uuid-123"]
      }'

​
Step 6: Create Second User

# Login as second user (you'll need to create this user first)
TOKEN2="$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=user2@example.com&password=password2' | jq -r .access_token)"

​
Step 7: Grant Permission to Second User

curl -X POST "http://localhost:8000/api/v1/permissions/datasets/user2-uuid-789?permission_name=read&dataset_ids=dataset-uuid-123" \
  -H "Authorization: Bearer $TOKEN1"

​
Step 8: Second User Searches Shared Dataset

curl -X POST "http://localhost:8000/api/v1/search" \
  -H "Authorization: Bearer $TOKEN2" \
  -H "Content-Type: application/json" \
  -d '{
        "search_type": "GRAPH_COMPLETION",
        "query": "What is this document about?",
        "dataset_ids": ["dataset-uuid-123"]
      }'
Result: Second user can now search the shared dataset and get results.

​
Example: Using Python SDK

This example shows the same workflow using the Python SDK.

​
Step 1: Enable Multi-Tenant Mode

import os
os.environ["ENABLE_BACKEND_ACCESS_CONTROL"] = "True"

​
Step 2: Add Data and Create Dataset

import asyncio
import cognee

async def main():
    # Add data (creates dataset automatically)
    await cognee.add("This is important project documentation", dataset_name="project_docs")
    
    # Build knowledge graph
    await cognee.cognify()
    
    # Search
    results = await cognee.search("What is this about?")
    print(results)

asyncio.run(main())

​
Step 3: Grant Permissions Programmatically

import asyncio
from uuid import UUID
from cognee.modules.users.methods import get_default_user, get_user
from cognee.modules.users.permissions.methods import give_permission_on_dataset

async def main():
    # Get current user
    owner = await get_default_user()
    
    # Get other user (you'll need their UUID)
    other_user = await get_user(UUID("other-user-uuid-here"))
    
    # Grant read permission on dataset
    await give_permission_on_dataset(other_user, UUID("dataset-uuid-here"), "read")

asyncio.run(main())

​
Common Issues

Permission denied:
  • Check user has required permission on the dataset
  • Verify dataset UUID is correct
  • Use dataset_ids instead of datasetName for cross-owner datasets
Empty search results:
  • Confirm user has read permission
  • Check dataset exists and contains data
  • Verify search query syntax
Data isolation issues:
  • Confirm ENABLE_BACKEND_ACCESS_CONTROL=true is set
  • Check database files exist: ls -la .cognee_system/databases/<user_uuid>/
  • Verify file storage isolation: ls -la .data_storage/<tenant_uuid_or_user_uuid>/
Authentication problems:
  • Verify token is valid and not expired
  • Check API server is running
  • Confirm credentials are correct

Setup Configuration

Configure multi-tenant mode

Core Concepts

Understand multi-tenant fundamentals

API Reference

Explore all API endpoints