Permission Snippets - Cognee Documentation

This guide provides practical code snippets demonstrating the permission system in action. These snippets show how to create users, tenants, roles, and datasets, and how to manage permissions effectively.

Complete snippets — All code snippets are complete and runnable, showing the full workflow from setup to permission management.

Creating a User

Users are the foundation of the permission system. Here’s how to create a new user:

from cognee.modules.users.methods import create_user

user = await create_user(
    email="alice@company.com",
    password="password123",
    is_superuser=True
)

Creating a Tenant

Tenants group users together and can receive permissions. Create a tenant with an owner:

from cognee.modules.users.tenants.methods import create_tenant

# Assuming user is already created
await create_tenant("acme_corp", user.id)

Adding Users to a Tenant

Add existing users to a tenant. Only the tenant owner can add users:

from cognee.modules.users.tenants.methods import add_user_to_tenant

# Assuming user2, tenant_id, and owner_id are already defined
await add_user_to_tenant(user2.id, tenant_id, owner_id)

Creating a Role

Roles provide permission groups within a tenant. Create a role for the tenant:

from cognee.modules.users.roles.methods import create_role

# Assuming owner_id is the tenant owner
await create_role("editor", owner_id)

Creating a Dataset

Datasets are the core data containers. Create a dataset with automatic permissions for the creator:

from cognee.modules.data.methods import create_authorized_dataset

# Assuming user is already created
dataset = await create_authorized_dataset("project_docs", user)

Granting Read Permission

Grant specific permissions to principals. Give read access to a user:

from cognee.modules.users.permissions.methods import give_permission_on_dataset

# Assuming user2 and dataset are already created
await give_permission_on_dataset(user2, dataset.id, "read")

Granting Multiple Permissions

Each call grants exactly one permission name, so write a separate call per permission. Give comprehensive access:

from cognee.modules.users.permissions.methods import give_permission_on_dataset

# Assuming user2 and dataset are already created
await give_permission_on_dataset(user2, dataset.id, "read")
await give_permission_on_dataset(user2, dataset.id, "write")
await give_permission_on_dataset(user2, dataset.id, "delete")

The four valid permission_name values are "read", "write", "delete", and "share". Passing any other value raises PermissionNotFoundError.

Owner Full Access + Read-Only Collaborator

The most common pattern: the creator gets full control, a teammate gets read-only access.create_authorized_dataset automatically grants the creator all four permissions (read, write, delete, share) on the new dataset — no extra calls are needed for the owner. To share with another user, call give_permission_on_dataset once per permission you want to grant.

from cognee.modules.data.methods import create_authorized_dataset
from cognee.modules.users.permissions.methods import give_permission_on_dataset

# Creator gets read + write + delete + share automatically
dataset = await create_authorized_dataset("research_docs", owner)

# Collaborator gets read-only — nothing else implied
await give_permission_on_dataset(reader, dataset.id, "read")

To upgrade the collaborator to read + write later, grant "write" as a separate call — it does not replace the existing "read" grant:

await give_permission_on_dataset(reader, dataset.id, "write")
# reader now has both read and write; the read entry is unchanged

Use revoke_permission_on_dataset to remove a specific permission later.

Repeated Grants and Idempotency

give_permission_on_dataset is insert-only and idempotent. Calling it again with the same (principal, dataset_id, permission_name) does not create a duplicate ACL row, does not bump updated_at, and does not raise — the existing row is left as-is.

# First call: inserts an ACL row granting read.
await give_permission_on_dataset(user2, dataset.id, "read")

# Second call with the same arguments: no-op. No new row, no update.
await give_permission_on_dataset(user2, dataset.id, "read")

This means it is safe to re-run grant logic on startup or in setup scripts. It also means it cannot be used to “change” a permission — if user2 already has read and you want them to have write instead, you must explicitly revoke read and grant write. See the revoke_permission_on_dataset function in ACL.

Checking User Permissions

Query what datasets a user can access. Check permissions by type:

from cognee.modules.users.permissions.methods import get_all_user_permission_datasets

# Assuming user is already created
# Get all datasets user can read
readable_datasets = await get_all_user_permission_datasets(user, "read")

# Get all datasets user can write
writable_datasets = await get_all_user_permission_datasets(user, "write")

Complete Permission Setup

Set up a complete permission scenario from scratch. This example shows the full workflow:

from cognee.modules.users.methods import create_user, get_user
from cognee.modules.users.tenants.methods import create_tenant, add_user_to_tenant
from cognee.modules.data.methods import create_authorized_dataset
from cognee.modules.users.permissions.methods import give_permission_on_dataset

# 1. Create users
user1 = await create_user("alice@company.com", "password123", is_superuser=True)
user2 = await create_user("bob@company.com", "password456")

# 2. Create tenant and add users
await create_tenant("acme_corp", user1.id)
# Refresh user1 to get tenant_id
user1 = await get_user(user1.id)
await add_user_to_tenant(user2.id, user1.tenant_id, user1.id)

# 3. Create dataset
dataset = await create_authorized_dataset("confidential_docs", user1)

# 4. Grant different permissions
await give_permission_on_dataset(user2, dataset.id, "read")  # Read-only access

Permission Inheritance Example

Demonstrate how permissions flow through the hierarchy. Show tenant and role inheritance:

from cognee.modules.users.permissions.methods import give_permission_on_dataset

# Assuming tenant, role, and dataset are already created
# Grant permission to tenant (all users inherit)
await give_permission_on_dataset(tenant, dataset.id, "read")

# Grant permission to role (role members inherit)
await give_permission_on_dataset(role, dataset.id, "write")

# User gets both: read (from tenant) + write (from role)

Multi-tenant Organization Setup

Create organization with multiple teams:

# Create organization with multiple teams
# 1. Create tenant
tenant = await create_tenant("tech_company", admin_user.id)

# 2. Create roles for different teams
dev_role = await create_role("developers", admin_user.id)
qa_role = await create_role("qa_team", admin_user.id)
pm_role = await create_role("product_managers", admin_user.id)

# 3. Create datasets for different projects
frontend_dataset = await create_authorized_dataset("frontend_docs", admin_user)
backend_dataset = await create_authorized_dataset("backend_docs", admin_user)
qa_dataset = await create_authorized_dataset("qa_docs", admin_user)

# 4. Grant role-based permissions
await give_permission_on_dataset(dev_role, frontend_dataset.id, "write")
await give_permission_on_dataset(dev_role, backend_dataset.id, "write")
await give_permission_on_dataset(qa_role, qa_dataset.id, "write")
await give_permission_on_dataset(pm_role, frontend_dataset.id, "read")
await give_permission_on_dataset(pm_role, backend_dataset.id, "read")

Temporary Access Management

Grant temporary access to external contractor:

# Grant temporary access to external contractor
contractor = await create_user("contractor@external.com", "temp_password")

# Grant read access to specific dataset
await give_permission_on_dataset(contractor, project_dataset.id, "read")

# Later, revoke access by removing the permission
# (This would require a revoke_permission function)

Cross-team Collaboration

Allow teams to collaborate on shared datasets:

# Allow teams to collaborate on shared datasets
shared_dataset = await create_authorized_dataset("shared_research", admin_user)

# Grant different levels of access to different teams
await give_permission_on_dataset(dev_role, shared_dataset.id, "read")
await give_permission_on_dataset(research_role, shared_dataset.id, "write")
await give_permission_on_dataset(management_role, shared_dataset.id, "read")

Best Practices

Follow these best practices for permission management:

Start simple — Begin with basic user and dataset creation
Use roles for teams — Create roles for different job functions
Grant tenant permissions — Use tenant-level permissions for organization-wide access
Regular audits — Periodically review and update permissions
Document access patterns — Keep clear records of who has access to what
Test permission changes — Verify permissions work as expected after changes

Setup Configuration

Learn how to configure the permission system

API Reference

Explore permission system API endpoints