- name
- cognee-permissions
- description
- Use when working with cognee's users, permissions, and multi-tenancy — creating users, tenants and roles, sharing datasets (read/write/delete/share grants), acting as a specific user in the SDK or authenticating over HTTP (login, API keys), turning access control on or off, debugging PermissionDeniedError or missing datasets, or understanding where permissions are enforced and how datasets are isolated.
Users, permissions, and multi-tenancy
Every dataset belongs to an owner, and every operation on it is checked
against a grant: a principal (user, role, or tenant) holding a
permission (read, write, delete, share) on a dataset. With access
control on (the default), each user+dataset pair also gets its own graph and
vector databases.
Use it
Act as a user in the SDK
Without user=, SDK calls run as the default user
([email protected], or DEFAULT_USER_EMAIL). To act as someone
else, create or load them and pass user=:
import cognee
from cognee.modules.users.methods import create_user, get_user
alice = await create_user("[email protected]", "password")
bob = await create_user("[email protected]", "password")
res = await cognee.remember("Alice's notes", dataset_name="alice_notes", user=alice)
await cognee.recall("What are the notes about?", user=alice, datasets=["alice_notes"])
remember, recall, search, forget, improve and the dataset helpers
all take user=.
Share a dataset
The caller must hold share on the dataset. Share by dataset id:
from uuid import UUID
from cognee.modules.users.permissions.methods import (
authorized_give_permission_on_datasets,
authorized_revoke_permission_on_datasets,
)
await authorized_give_permission_on_datasets(
bob.id, # principal: a user, role, or tenant id
[UUID(res.dataset_id)], # dataset ids (RememberResult.dataset_id is a str)
"read", # "read" | "write" | "delete" | "share"
alice.id, # the owner making the grant
)
await cognee.recall("...", user=bob, dataset_ids=[UUID(res.dataset_id)]) # by id (must be a UUID)
Bob must address Alice's dataset by id: dataset names resolve only among the caller's own datasets.
Tenants and roles (organizations and groups)
from cognee.modules.users.tenants.methods import add_user_to_tenant, create_tenant, select_tenant
from cognee.modules.users.roles.methods import add_user_to_role, create_role
tenant_id = await create_tenant("Acme", alice.id) # alice owns it
await select_tenant(user_id=alice.id, tenant_id=tenant_id)
role_id = await create_role(role_name="Researcher", owner_id=alice.id)
await add_user_to_tenant(user_id=bob.id, tenant_id=tenant_id, owner_id=alice.id)
await add_user_to_role(user_id=bob.id, role_id=role_id, owner_id=alice.id)
await select_tenant(user_id=bob.id, tenant_id=tenant_id)
alice = await get_user(alice.id) # reload after changing the active tenant
res = await cognee.remember(text, dataset_name="acme_docs", user=alice)
await authorized_give_permission_on_datasets(role_id, [UUID(res.dataset_id)], "read", alice.id)