Cognee Permissions

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):

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.