> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Principals

> The unified abstraction for entities that can hold permissions in Cognee.

# 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.

<Info>**Polymorphic design** — All principal types use the same permission mechanism, making the system flexible and consistent.</Info>

## Principal Types

There are three types of principals:

* **[Users](./users)** — Individual people who interact with the system
* **[Tenants](./tenants)** — Organizations or groups that contain users
* **[Roles](./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](./users) for personal access
* [Tenants](./tenants) for organization-wide access
* [Roles](./roles) for team-based access within a tenant

<Accordion title="Principal Model Fields">
  The base Principal model defines what gets stored in the SQL database. The `principals` table contains:

  * `id`: Unique identifier (UUID primary key)
  * `created_at`: Timestamp when created
  * `updated_at`: Timestamp when last modified
  * `type`: Discriminator field for polymorphic inheritance

  Each principal type (User, Tenant, Role) has its own table that references the principals table via foreign key, storing additional fields specific to that type.
</Accordion>

<Accordion title="Permission Storage Schema">
  The permission system links principals to datasets with permissions:

  * `principal_id`: References the principal ([user](./users), [tenant](./tenants), or [role](./roles))
  * `dataset_id`: References the [dataset](./datasets)
  * `permission_id`: References the permission type

  This many-to-many relationship allows flexible permission management across different entity types.
</Accordion>

<Accordion title="Key Functions">
  * `give_permission_on_dataset(principal, dataset_id, permission)`: Writes a single ACL row (or reuses an existing one) so a [user](./users), [tenant](./tenants), or [role](./roles) gains read, write, delete, or share on that dataset. It's the building block used after dataset creation or whenever access is delegated.

  * `get_principal_datasets(principal, permission)`: Queries those ACL entries (and the related dataset records) so you can list every dataset where that same principal holds the requested permission—handy for permission checks or UI listings. It takes a principal object and performs no authorization of its own, so call it only when you have already established that the caller may ask about that principal.

  * `authorized_get_principal_datasets(principal_id, permission_name, requester_id)`: The authorization-checked entry point for the same lookup, importable from `cognee.modules.users.permissions.methods`. It takes the principal's id rather than the object, resolves the requester, checks that they may ask about that principal, and returns the resulting `list[Dataset]`. This is what backs `GET /api/v1/permissions/principals/{principal_id}/datasets`.

    The requester's [tenant](./tenants) is read off the requester rather than passed in, so a caller cannot name a different tenant, and the returned datasets are always filtered down to that tenant. Which principals a requester may ask about depends on the principal's type:

    * **[User](./users)** — themselves, or any user in the tenant if they are the tenant owner or have user-management permission.
    * **[Role](./roles)** — a role of their tenant that they are a member of, or any role of that tenant if they are the tenant owner or have user-management permission. A `principal_id` for a role in another tenant raises `RoleNotFoundError` (`404`), which is indistinguishable from a role that does not exist.
    * **[Tenant](./tenants)** — only the tenant they are currently in; any other tenant raises `PermissionDeniedError` (`403`).

    Anything else — including an unsupported principal type, or a requester who fails the tenant-owner-or-user-management check the rules above fall back to — raises `PermissionDeniedError` (`403`).
</Accordion>

## Permission Inheritance

The principal system supports hierarchical permission inheritance:

1. **Direct permissions** — Explicitly granted to a specific principal
2. **[Role permissions](./roles)** — Inherited through role memberships
3. **[Tenant permissions](./tenants)** — Inherited through tenant membership

When a [user](./users) 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](./tenants) level
* Refine access with [role](./roles)-specific permissions
* Override with direct [user](./users) 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

<Columns cols={2}>
  <Card title="Users" icon="user" href="/core-concepts/multi-user-mode/permissions-system/users">
    Learn about individual users and authentication
  </Card>

  <Card title="Tenants" icon="building" href="/core-concepts/multi-user-mode/permissions-system/tenants">
    Understand organization-level access control
  </Card>
</Columns>