Loading
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 aut
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add topoteretes/cognee --skill cognee-permissions -a cursor -y
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.
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.
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.
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=.
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.
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)
select_tenant; None is the
personal space). Datasets are created in the active tenant.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.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).
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>.POST /api/v1/auth/api-keys creates one (GET lists,
DELETE /api-keys/{id} removes); send it as X-Api-Key: <key>.DEFAULT_USER_PASSWORD is set (the server logs a warning at startup)./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) |
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 [email protected].
PermissionDeniedError (HTTP 403).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.[].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).select_tenant (get_user(id)): an old User
object still carries the previous active tenant."notes" datasets are unrelated.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").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.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.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.A grant is one ACL row: principal × permission × dataset
(cognee/modules/users/models/ACL.py).
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.permissions/permission_types.py):
read, write, delete, share. share gates granting and revoking.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:
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.authorized_give_permission_on_datasets /
authorized_revoke_permission_on_datasets).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 |
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.
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).
cognee/modules/users/models/ (ACL, Principal, Permission,
Role, Tenant, UserRole, UserTenant, DatasetDatabase,
UserApiKey, PrincipalCapability)cognee/modules/users/methods/,
cognee/modules/users/tenants/methods/, cognee/modules/users/roles/methods/cognee/modules/users/permissions/methods/cognee/modules/users/authentication/,
cognee/api/v1/users/routers/, cognee/api/v1/api_keys/routers/cognee/api/v1/permissions/routers/get_permissions_router.pyget_authorized_existing_datasets with the right permission before doing
any work; never read a dataset by id without that check.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.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.cognee/tests/unit/users/, cognee/tests/unit/modules/users/, and
the examples above.