​
Principals: The Abstraction

A principal is any entity that can hold permissions in Cognee. This abstraction allows the permission system to work with different types of entities in a unified way, eliminating the need for separate permission systems for users, tenants, and roles.
Polymorphic design — All principal types use the same permission mechanism, making the system flexible and consistent.

​
Principal Types

There are three types of principals:
  • Users — Individual people who interact with the system
  • Tenants — Organizations or groups that contain users
  • Roles — Groups of users within a tenant
All three types inherit from the same base Principal class, which means they can all be granted permissions on datasets using the same functions and mechanisms.

​
How Principals Work with Permissions

The system stores permissions by linking principals to datasets. You can grant permissions to any of the principals using built-in functions like give_permission_on_dataset() and get_principal_datasets(). When you grant a permission, you specify:
  • Which principal gets the permission
  • Which dataset the permission applies to
  • What type of permission (read, write, delete, share)
This unified approach means you can grant permissions to:
  • Individual users for personal access
  • Tenants for organization-wide access
  • Roles for team-based access within a tenant

​
Permission Inheritance

The principal system supports hierarchical permission inheritance:
  1. Direct permissions — Explicitly granted to a specific principal
  2. Role permissions — Inherited through role memberships
  3. Tenant permissions — Inherited through tenant membership
When a user tries to access data, the system evaluates their effective permissions by combining all three sources. This allows for flexible access control patterns:
  • Grant broad permissions at the tenant level
  • Refine access with role-specific permissions
  • Override with direct user permissions when needed

​
Benefits of the Principal System

  • Unified interface — Same functions work for all principal types
  • Flexible access control — Support for individual, team, and organization-level permissions
  • Scalable management — Easy to add new principal types or modify existing ones
  • Consistent behavior — All principals follow the same permission rules and patterns

Users

Learn about individual users and authentication

Tenants

Understand organization-level access control