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 (default_user@example.com, 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("alice@example.com", "password")
bob = await create_user("bob@example.com", "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)

• A user acts inside one active tenant (select_tenant; None is the personal space). Datasets are created in the active tenant.
• The granter can only share datasets in their current active tenant (others raise PermissionDeniedError). The principal's tenant is not checked: a grant to a role on a personal dataset (or one from another tenant) succeeds, and its members see it only while their active tenant is the dataset's tenant (personal space for a personal dataset). To share inside a tenant, create the dataset with that tenant active.
• Members of a role or tenant get its grants. A granted dataset is visible only while the member's active tenant is the dataset's tenant (select_tenant, then reload the user); a personal dataset is visible only in personal space.

Full walkthrough: examples/demos/permissions/user_permissions_and_access_control_example.py (also tenant_role_setup_example.py, tenant_role_constraints_example.py).

Over HTTP

• Register / log in: POST /api/v1/auth/register, then POST /api/v1/auth/login (form fields username, password). The response sets an auth cookie and returns {"access_token", "token_type": "bearer"}; send Authorization: Bearer <token>.
• API keys: POST /api/v1/auth/api-keys creates one (GET lists, DELETE /api-keys/{id} removes); send it as X-Api-Key: <key>.
• Default user over HTTP: it has no password unless DEFAULT_USER_PASSWORD is set (the server logs a warning at startup).
• Permissions routes (/api/v1/permissions):

Endpoint	What it does
POST /datasets/{principal_id}?permission_name=read + JSON body [dataset_ids]	Grant (needs share)
DELETE /datasets/{principal_id}	Revoke
GET /principals/{principal_id}/datasets?permission_name=read	Datasets a principal holds a permission on
POST /tenants · POST /tenants/select · GET /tenants/me	Create, switch, list your tenants
POST /users/{user_id}/tenants · DELETE /tenants/{tenant_id}/users/{user_id}	Add/remove a tenant member
GET /tenants/{tenant_id}/users	Tenant members
POST /roles · DELETE /roles/{role_id} · GET /tenants/{tenant_id}/roles	Manage roles
POST / DELETE /users/{user_id}/roles	Add/remove a role member
GET /tenants/{tenant_id}/roles/{role_id}/users · GET /tenants/{tenant_id}/roles/users/{user_id}	Role members; a user's roles (404 if not a member)

Turning access control off

ENABLE_BACKEND_ACCESS_CONTROL is the master switch:

• true (default): multi-tenant. API calls require auth, every dataset operation is permission-checked, and each user+dataset gets isolated graph and vector databases.
• false: single-user storage. ACL checks still run, but they only gate which dataset ids may be named: retrieval runs over the shared graph and vector databases, so other users' content is not filtered out. Every user reads and writes the same shared databases. Use it only for a single-user deployment.

Authentication follows the switch unless REQUIRE_AUTHENTICATION is set. REQUIRE_AUTHENTICATION=true with access control off keeps logins but not isolation; REQUIRE_AUTHENTICATION=false with access control on is ignored (auth is forced on with a warning).

For production multi-tenant deployments (managed isolation, the production Postgres adapter, and horizontal scaling), contact social@cognee.ai.

Pitfalls

• Denied is not the same as empty.
  • Asking for a dataset id you cannot read raises PermissionDeniedError (HTTP 403).
  • On recall/search, a dataset name that is not yours raises DatasetNotFoundError, even if it is shared with you. On writes (remember/add/cognify) it silently creates a new dataset of your own with that name. Use the id.
  • Passing no datasets searches only what you can read, so a user with no grants simply gets [].
• Grants need share on a dataset in the granter's active tenant; otherwise PermissionDeniedError. The principal's tenant is not checked, so a grant can succeed yet be visible to its members only in the dataset's tenant (see above).
• Reload the user after select_tenant (get_user(id)): an old User object still carries the previous active tenant.
• Same name, different datasets. Dataset ids are per owner and tenant, so two users' "notes" datasets are unrelated.
• Unsupported backends are a hard error. With access control on, both the graph and vector backends need a dataset-database handler. If either lacks one (e.g. Neptune, Neptune Analytics, most community vector adapters), cognee raises OSError naming it (multi_user_support_possible() in cognee/context_global_variables.py), never a silent fall back to shared databases. Switch backends or set ENABLE_BACKEND_ACCESS_CONTROL=false. The support matrix is in CLAUDE.md ("Multi-Tenant Access Control").
• User management is a capability. manage_users is a tenant-scoped capability in principal_capabilities, granted to a tenant (every member), a role (its members) or a user (that person, in that tenant) and resolved as their union (get_effective_capabilities); the tenant owner holds every capability. Every check goes through has_grant_permission(requester, tenant, capability); has_user_management_permission is that check for manage_users. Creating roles, assigning them and adding users to a tenant need manage_users, not ownership. Assigning a role has one more rule (require_role_capabilities): the requester must hold every capability the role carries, and a role named admin counts as carrying all of them.
• Grant/revoke endpoints ride the permissions router (POST/DELETE /permissions/capabilities/{principal_id}) and are gated by capabilities of their own: granting needs grant_capabilities, revoking needs revoke_capabilities, and neither comes with manage_users. A granter can only pass on capabilities they hold themselves (get_unheld_capabilities). Each row records who made the grant in granted_by; both endpoints take capability repeated to grant or revoke several at once, all or nothing. For a user principal the grant lands in the tenant_id given, or the caller's current tenant, and the user must already be a member of it (CapabilityGrantToNonMemberError, 403, says so); a role or tenant principal always uses its own tenant. A missing principal or tenant answers like a refusal (403), so the endpoints do not reveal which ids exist. Removing a user from a tenant drops their personal capabilities there, and deleting a role drops the role's.
• Deprecated fallback: the admin role name. Members of a role named admin (LEGACY_ALL_CAPABILITY_ROLE_NAMES) pass every capability check until the role is granted the capabilities it needs; the fallback sits in has_grant_permission, so it also passes the grant and revoke checks.

How it works

The model

A grant is one ACL row: principal × permission × dataset (cognee/modules/users/models/ACL.py).

• Principal (Principal.py) is polymorphic: User, Role, and Tenant all inherit from it, so one ACL row can cover every member of a role or tenant.
• Permission is one of four names (permissions/permission_types.py): read, write, delete, share. share gates granting and revoking.
• Membership (UserRole, UserTenant) is separate from grants. A user's access is the union of their own grants and those of their roles and tenants.

Grants come from:

1. Dataset creation (cognee/modules/data/methods/create_authorized_dataset.py): the creator gets all four permissions. If the creator has a parent_user_id (a sub-user or agent identity, create_user(..., parent_user_id=...)), the parent gets all four too.
2. Explicit sharing (authorized_give_permission_on_datasets / authorized_revoke_permission_on_datasets).

Where it is enforced

Most entry points resolve datasets through get_authorized_existing_datasets(datasets, permission, user) (cognee/modules/data/methods/); all of them end in get_specific_user_permission_datasets / get_all_user_permission_datasets (cognee/modules/users/permissions/methods/):

Operation	Permission
remember / add / cognify / improve	write
recall / search / visualize	read
forget / delete / empty a dataset	delete
grant / revoke	share

Isolation

With access control on, each user+dataset pair has its own graph and vector databases, recorded in the DatasetDatabase model (names, providers, handlers, connection info, migration revision). The relational database (users, ACLs, the registry) is always shared. The handler is chosen from the configured providers; the registry is cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py. The *_shared handlers (pgvector_shared, postgres_graph_shared) give each dataset its own Postgres schema inside cognee's main database instead of a separate database, so no CREATE DATABASE privilege is needed. Select them with VECTOR_DATASET_DATABASE_HANDLER / GRAPH_DATASET_DATABASE_HANDLER.

Seeing grants

cognee/api/v1/visualize/memory_provenance.py renders ACL grants as edges from principal to dataset (reads, writes, can_delete, can_share), served by the schema router (visualize_memory_provenance HTML, get_memory_provenance_payload JSON).

Key files

• Models: cognee/modules/users/models/ (ACL, Principal, Permission, Role, Tenant, UserRole, UserTenant, DatasetDatabase, UserApiKey, PrincipalCapability)
• Users, tenants, roles: cognee/modules/users/methods/, cognee/modules/users/tenants/methods/, cognee/modules/users/roles/methods/
• Grants and checks: cognee/modules/users/permissions/methods/
• Auth: cognee/modules/users/authentication/, cognee/api/v1/users/routers/, cognee/api/v1/api_keys/routers/
• HTTP permissions API: cognee/api/v1/permissions/routers/get_permissions_router.py

Extending it

• New operation on a dataset: resolve it through get_authorized_existing_datasets with the right permission before doing any work; never read a dataset by id without that check.
• New backend: implement a DatasetDatabaseHandlerInterface and register it in the handler registry (or at runtime with use_dataset_database_handler()), otherwise multi-tenant mode refuses to start with it.
• New capability: add the name to CAPABILITY_TYPES in permission_types.py and gate the operation with has_grant_permission(requester_id, tenant_id, <name>); the owner holds it immediately, everyone else once it is granted. Dataset permissions (read/write/delete/share) stay in the ACL and are rejected by validate_capability.
• Tests: cognee/tests/unit/users/, cognee/tests/unit/modules/users/, and the examples above.