--- name: cognee-permissions description: Use when working with cognee's permission system — understanding or changing how users, roles, and tenants get access to datasets, how ACL grants work, where permissions are enforced in add/cognify/search/delete, and how the grant records surface in the memory-provenance view. ---

# The cognee permission system

## The master switch

`ENABLE_BACKEND_ACCESS_CONTROL` decides whether any of this runs:

- `true` (default): multi-tenant mode. Every API call requires auth, every dataset operation is permission-checked, and each user+dataset pair gets isolated graph/vector/relational databases (tracked in the `DatasetDatabase` model, supported backends: Kuzu, LanceDB, SQLite, Postgres). - `false`: single-user mode. Permission checks short-circuit to allowed, there is no per-dataset isolation, and **every user's operations resolve to the same shared databases and datasets**. Authentication is a separate knob: `REQUIRE_AUTHENTICATION`. Unset, it inherits this switch (so turning access control off also turns auth off) — but if `REQUIRE_AUTHENTICATION=true` is set, endpoints still demand a login; authenticated users are identified but *not isolated*, all pointing at the same data. The reverse misconfiguration (`REQUIRE_AUTHENTICATION=false` with access control on) is ignored: auth is forced on with a warning, because multi-tenant isolation is meaningless without identity (`get_authenticated_user.py`).

## The core model: principals, permissions, ACL grants

Everything reduces to one relation — **a grant**: *principal* × *permission* × *dataset*, stored as one `ACL` row (`modules/users/models/ACL.py`).

- **Principal** (`Principal.py`) is polymorphic: `User`, `Role`, and `Tenant` all inherit from it. Any of the three can hold a grant, which is how role-wide and tenant-wide access work — one ACL row covers every member. - **Permission** (`Permission.py`) is one of exactly four names, defined in `permissions/permission_types.py`: `read`, `write`, `delete`, `share`. `share` is the meta-permission: it gates granting/revoking access for others. - **Membership** is separate from grants: `UserRole` and `UserTenant` link users into roles/tenants. A user's effective access is the union of their own grants and the grants of every role/tenant they belong to.

## How grants come into existence

1. **Dataset creation** (`modules/data/methods/create_authorized_dataset.py`): the creating user is granted **all four permissions** on the new dataset. If the user has a `parent_user_id` (sub-users/agent identities), the parent is auto-granted all four as well — parents always see their children's datasets. 2. **Explicit sharing** (`permissions/methods/ authorized_give_permission_on_datasets.py`): the caller must hold `share` on the target datasets, then any principal (user, role, or tenant) can be granted any permission. Revocation mirrors this (`authorized_revoke_permission_on_datasets.py`). 3. **Capabilities — tenant-scoped grants of actions, not data** (landing via PR #4302, currently in review): a new `principal_capabilities` table, keyed on `(principal, tenant, capability)`. Where an ACL row grants access to *a dataset*, a capability grants *an action inside a tenant* — the first one being `manage_users`. The catalog of capability names is code (`CAPABILITY_TYPES` in `permission_types.py`), not a database table, "because the code is what gives each name meaning"; only the assignment of a capability to a principal is data. `tenant_id` is stored on every row because a user can belong to multiple tenants: it pins each grant to the user's membership in one specific tenant, so holding a capability in one tenant never carries over to the same user's other tenants. Resolution (`get_effective_capabilities(user, tenant)`) returns the union of what the tenant grants all of its members, what the user's roles in that tenant grant, and what the user was granted personally — there is no deny in the model, resolution is gated on actual tenant membership, and the tenant owner short-circuits as holding every capability. Grant/revoke endpoints ride the permissions router.

## Where permissions are enforced

The single chokepoint for dataset resolution is `get_authorized_existing_datasets(datasets, permission, user)` — every entrypoint resolves names/IDs through it with the permission it needs:

| Operation | Required permission | Enforcement path | |---|---|---| | `add` / `cognify` / `remember` | `write` | dataset resolution before the pipeline runs | | `search` / `recall` / visualize | `read` | dataset resolution; retrieval is restricted to documents of readable datasets | | `delete` / prune of a dataset | `delete` | `datasets.py` resolves with `"delete"` | | grant/revoke for others | `share` | `authorized_give/revoke_permission_on_datasets` |

Two behaviors worth knowing:

- **Denied reads return empty results, not 403.** A search against a dataset you cannot read yields `[]` — deliberate, to avoid leaking which datasets exist. When debugging "search returns nothing", check grants before checking the graph.

## Roles, tenants, and who may manage them

- **User management** (listing tenant users, assigning/removing roles, adding/removing users) is allowed for the **tenant owner** always, and today for members of roles named in `USER_MANAGEMENT_ALLOWED_ROLE_NAMES` (currently `{"admin"}`, `permissions/permission_types.py`). That name-matching is a known footgun — any customer group that happens to be called "admin" gets user management — and PR #4302 replaces it: the check becomes "does the requester hold the `manage_users` capability in this tenant" (owner always passes), with the role-name match kept only as a deprecated fallback so tenants upgrading from the old check don't lose user management until their `admin` role is granted the capability. - **Role visibility**: members of a role can see the role itself and their co-members; anyone with user-management permission sees all (`tenants/methods/get_users_in_role.py`). Lookups are tenant-scoped — a role id from another tenant cannot be used to read that tenant's members.

## The grant records in memory provenance (the new grant view)

`api/v1/visualize/memory_provenance.py` surfaces the ACL grants as first-class graph data. Each grant becomes an `AclGrantRecord`:

```python {"principal_id": ..., "principal_kind": "user" | "role" | "tenant", "permission": ...} ```

and is rendered into the provenance graph as an edge from the principal node to the dataset, with the permission mapped to a relation name (`_ACL_EDGE_RELATIONS`):

| permission | provenance edge | |---|---| | read | `reads` | | write | `writes` | | delete | `can_delete` | | share | `can_share` |

Grants are rendered (never dropped) even when the principal is unknown, because "an ACL row exists because someone granted it". The view is exposed through the schema router (`get_schema_router.py`): `visualize_memory_provenance` (HTML) and `get_memory_provenance_payload` (JSON) — this is where you *see* the permission state of a memory rather than query it.

## HTTP API surface (`api/v1/permissions/routers/get_permissions_router.py`)

| Endpoint | What it does | |---|---| | `POST /permissions/datasets/{principal_id}` | grant a permission on datasets to a principal (requires `share`) | | `DELETE /permissions/datasets/{principal_id}` | revoke a permission | | `POST /permissions/roles` · `DELETE /permissions/roles/{role_id}` | create/delete a role | | `POST/DELETE /permissions/users/{user_id}/roles` | add/remove a user to/from a role | | `POST /permissions/users/{user_id}/tenants` | add a user to a tenant | | `GET /permissions/tenants/{tenant_id}/roles/{role_id}/users` | members of a role (self-visible to members) | | `GET /permissions/tenants/{tenant_id}/roles/users/{user_id}` | a user's roles | | `GET /permissions/tenants/{tenant_id}/users` | users in a tenant | | `GET /permissions/tenants/me` | the caller's tenants |

## Key files map

- Models: `cognee/modules/users/models/` — `ACL`, `Principal`, `Permission`, `Role`, `Tenant`, `UserRole`, `UserTenant`, `DatasetDatabase` (and `PrincipalCapability` once #4302 lands) - Methods: `cognee/modules/users/permissions/methods/` — grant/revoke, checks, dataset resolution, document filtering - Enforcement chokepoint: `cognee/modules/data/methods/` (`get_authorized_existing_datasets`, `create_authorized_dataset`) - Grant provenance view: `cognee/api/v1/visualize/memory_provenance.py` - HTTP API: `cognee/api/v1/permissions/routers/get_permissions_router.py`