Permission Snippets

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

Grant different permission types to the same principal. 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")

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

Setup Configuration

Learn how to configure the permission system

API Reference

Explore permission system API endpoints

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Setup Configuration

API Reference