Multi-Tenant Ready: Introducing Dataset Sharing & Role-Based Access

While we’re proud to have built a robust AI memory engine that reliably retains all ingested data, one recurring theme has crystalized in our users’ feedback: the need for a friction-free way to manage who can interact with stored knowledge.

Developers building on cognee often handle sensitive or team-specific data, so simple and intuitive access control is imperative. That’s why the latest version of cognee now includes a built-in user management system which lets users share datasets with precise role-based permissions.

This feature works seamlessly with Kùzu for graphs and LanceDB for vectors, ensuring security integrates naturally into your workflows.

The Permission Model: Scoped, Flexible, and Secure

In cognee, permissions revolve around datasets—self-contained units that bundle documents, metadata, and their graph/vector representations. Granting or revoking access to a dataset effectively controls interactions with its underlying databases.

Permissions are assigned to "principals," which can be:

• Tenants: Broad containers for organizations or isolated environments, ideal for SaaS providers or agencies managing multiple clients.
• Roles: Predefined groups like "Analyst," "Contributor," or custom ones you define, with adjustable defaults for efficiency.
• Users: Individual overrides for targeted access, such as giving a colleague temporary read rights to a prototype dataset.

Each principal supports four core permissions:

• Read: Query and retrieve from the dataset.
• Write: Add or update content.
• Delete: Permanently remove entries.
• Share: Delegate permission management to others.

This setup lets you start simple—assign to a user—and scale to roles or tenants as your project grows, all while maintaining clear boundaries.

Using Permissions Programmatically via the SDK

The SDK provides methods to create users, roles, tenants, and assign permissions.

Note: We've trimmed the full example script here to keep the focus on key steps like user creation, dataset addition, and permission granting. The complete, runnable version is available in our GitHub repo (see the examples folder for the detailed permissions demo).

First, enable backend access control and set up your environment:

import os
os.environ["ENABLE_BACKEND_ACCESS_CONTROL"] = "True"
os.environ["LLM_API_KEY"] = "your-api-key"  # Reference .env.template for other providers

Reset and initialize cognee with the necessary databases and tables for user management:

import cognee
from cognee.modules.engine.operations.setup import setup

await cognee.prune.prune_data()
await cognee.prune.prune_system(metadata=True)
await setup()

Create users and add datasets (trimmed; full includes paths and error handling):

from cognee.modules.users.methods import create_user

user_1 = await create_user("user_1@example.com", "example")
await cognee.add(["path/to/ai_document.pdf"], dataset_name="AI", user=user_1)

user_2 = await create_user("user_2@example.com", "example")
await cognee.add(["Quantum computing leverages superposition and entanglement."], dataset_name="QUANTUM", user=user_2)

Then cognify the datasets (extract IDs for later use; the full script includes a helper function):

ai_cognify_result = await cognee.cognify(["AI"], user=user_1)
quantum_cognify_result = await cognee.cognify(["QUANTUM"], user=user_2)

# Extract dataset IDs (full script has extract_dataset_id_from_cognify function)
ai_dataset_id = ...  # From ai_cognify_result
quantum_dataset_id = ...  # From quantum_cognify_result

Demonstrate permission checks (user_1 can query their own but not user_2's initially):

# user_1 queries own dataset successfully
search_results = await cognee.search(
    query_type=cognee.SearchType.GRAPH_COMPLETION,
    query_text="What is in the document?",
    user=user_1,
    datasets=[ai_dataset_id],
)

# user_1 attempts user_2's dataset (fails with PermissionDeniedError)
try:
    await cognee.search(..., datasets=[quantum_dataset_id], user=user_1)
except PermissionDeniedError:
    print("Access denied")

Grant permissions (user_2 gives read access to user_1; full includes write/delete examples):

await cognee.modules.users.permissions.methods.authorized_give_permission_on_datasets(
    user_1.id,
    [quantum_dataset_id],
    "read",
    user_2.id,  # As the owner
)

Now user_1 can query user_2's dataset. For roles/tenants (trimmed; full script shows adding users to them):

tenant_id = await cognee.modules.users.tenants.methods.create_tenant("CogneeLab", user_2.id)
role_id = await cognee.modules.users.roles.methods.create_role("Researcher", owner_id=user_2.id)

user_3 = await cognee.modules.users.methods.create_user("user_3@example.com", "example")
await cognee.modules.users.tenants.methods.add_user_to_tenant(user_3.id, tenant_id, owner_id=user_2.id)
await cognee.modules.users.roles.methods.add_user_to_role(user_3.id, role_id, owner_id=user_2.id)

# Grant to role
await cognee.modules.users.permissions.methods.authorized_give_permission_on_datasets(
    role_id,
    [quantum_dataset_id],
    "read",
    user_2.id,
)

This approach keeps your code clean while enforcing access in cases where data ownership matters.

Using Permissions via the cognee Backend with API Requests

For API-driven control, first make sure to have cognee installed, then configure any environment variables such as:

# Set your OpenAI LLM API key:
export LLM_API_KEY=your-access-key
# Backend access control has to be enabled: to run multi-user mode in Cognee
export ENABLE_BACKEND_ACCESS_CONTROL=True

Then start the cognee backend server:

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

With the cognee python library installed.

Note: The backend can be used with curl, but you can access Swagger docs at: http://localhost:8000/docs

Below are key curl examples (again, trimmed for brevity).

Here’s how to register users:

curl -X 'POST' \
  'http://localhost:8000/api/v1/auth/register' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user1@example.com",
  "password": "string",
  "is_active": true,
  "is_superuser": false,
  "is_verified": true
}'

# Repeat for user2@example.com

An example output of register endpoint (outputs include user IDs; copy and store them for later):

{
  "id": "603266b3-28ff-4a58-bf83-2d06e1c5701d",
  "email": "user2@example.com",
  "is_active": true,
  "is_superuser": false,
  "is_verified": false,
  "tenant_id": null
}

Now, if we login as user1:

curl -X 'POST' \
  'http://localhost:8000/api/v1/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username=user1%40example.com&password=string&scope=&client_id=string&client_secret=********'

The output of this call will give us the API key we need to use for other cognee endpoints:

{
	"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxZjhlMjdjNS02NjEwLTQ5MGEtOTFlYS01ZGNlNTAwZDEzOWQiLCJhdWQiOlsiZmFzdGFwaS11c2VyczphdXRoIl0sImV4cCI6MTc1ODcxODQ3Mn0.xHrB-pdwt-V-qiDkvjfKkiJhgB1gUPLtz71ZecOff70", 
	"token_type": "bearer"
}  

We need to copy this bearer access_token and include it in our future requests towards cognee.

Add and cognify data as user1 (trimmed; the full example includes file uploads and outputs dataset_id):

curl -X 'POST' 'http://localhost:8000/api/v1/add' \
  -H 'Authorization: Bearer [user1_token]' \
  -F 'data=@"/path/to/document.txt"' \
  -F 'datasetName="string"'

curl -X 'POST' 'http://localhost:8000/api/v1/cognify' \
  -H 'Authorization: Bearer [user1_token]' \
  -d '{"datasets": ["string"]}'

Search as user1 succeeds; the full output shows results):

curl -X 'POST' 'http://localhost:8000/api/v1/search' \
  -H 'Authorization: Bearer [user1_token]' \
  -d '{"searchType": "GRAPH_COMPLETION", "query": "What'\''s in the document?", "datasetIds": ["[dataset_id]"]}'

Attempting to search as user2 initially fails, returning an empty array:

[]

User2 can be granted read access for user1’s dataset by user1, with these stipulations:

1. API key / bearer token has to be from user 1
2. Id for user 2 needs to be part of the URL of the request

Permission is granted using this command:

curl -X 'POST' \
  'http://localhost:8000/api/v1/permissions/datasets/603266b3-28ff-4a58-bf83-2d06e1c5701d?permission_name=read' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxZjhlMjdjNS02NjEwLTQ5MGEtOTFlYS01ZGNlNTAwZDEzOWQiLCJhdWQiOlsiZmFzdGFwaS11c2VyczphdXRoIl0sImV4cCI6MTc1ODcxODQ3Mn0.xHrB-pdwt-V-qiDkvjfKkiJhgB1gUPLtz71ZecOff70' \
  -d '[
  "7b137d19-d1e8-5ff4-b7d7-ed94a5d1d18b"
]'

Success produces the following response:

{
	"message":"Permission assigned to principal"
}

With this we can query user1’s dataset as user2 (now using user2’s API key / bearer token) and get proper search output:

curl --location 'http://127.0.0.1:8000/api/v1/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2MDMyNjZiMy0yOGZmLTRhNTgtYmY4My0yZDA2ZTFjNTcwMWQiLCJhdWQiOlsiZmFzdGFwaS11c2VyczphdXRoIl0sImV4cCI6MTc1ODcyMTQ2N30.u4DN92xaESqXvciZzbbvckM1lpCFqqkMIJDm8oP2gdo' \
--data '{
  "searchType": "GRAPH_COMPLETION",
  "query": "What'\''s in the document?",
  "datasetIds": ["7b137d19-d1e8-5ff4-b7d7-ed94a5d1d18b"]
}'

Note: Users can also be added to Roles and Tenants and then permission can be assigned on a Role/Tenant level—check the full API demo in the repo for those flows.

This API layer makes cognee adaptable for scripted automation or integration into larger systems, with built-in safeguards.

Secure What Matters, Share What Counts

With this granular control over datasets, tenants, roles, and users, cognee now allows you to handle access with the precision your projects demand—fostering collaboration while safeguarding knowledge.

We're looking forward to hearing how Permissions empower your workflows, from streamlining team access to securing client data.