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:
- 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.
- 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.
anthropics/skills180k
