Users
Users are the most common type of principal and the primary way people access the system. They authenticate through email and password and can own datasets, be granted permissions on others, and belong to at most one tenant.Default user behavior — When no user is specified, Cognee uses a default user with email “default_user@example.com” for development and testing.
User Authentication
Users authenticate through email and password. When no user is specified, Cognee uses a default user with email “default_user@example.com” for development and testing. A user without a tenant can still use the system but operates in isolation.User Management
Users can:- Own datasets and be granted permissions on others
- Belong to at most one tenant
- Have direct permissions on datasets
- Inherit permissions from their tenant and roles
User Model Fields
User Model Fields
The User model defines what gets stored in the SQL database. The
users table contains:id: Unique identifier (UUID primary key, references principals.id)email: User’s email address (unique)hashed_password: Encrypted passwordtenant_id: ID of the tenant the user belongs to (nullable)is_active: Whether the user account is activeis_verified: Whether the user’s email is verifiedis_superuser: Whether the user has superuser privileges
User Creation
User Creation
create_user(email, password, tenant_id=None, is_superuser=False): Creates a new user with specified credentials- Default user behavior: System creates “default_user@example.com” if no user exists
Environment Variables
Environment Variables
DEFAULT_USER_EMAIL: Override default user email (default: “default_user@example.com”)DEFAULT_USER_PASSWORD: Override default user password (default: “default_password”)REQUIRE_AUTHENTICATION: Enforce authentication on HTTP endpoints (default: “false”)FASTAPI_USERS_RESET_PASSWORD_TOKEN_SECRET: Secret for password reset tokensFASTAPI_USERS_VERIFICATION_TOKEN_SECRET: Secret for email verification tokens
Limitations
Limitations
- A user can belong to at most one tenant
- Users without a tenant exist but are isolated
- API endpoints for user management and authentication
User Permissions
Users can receive permissions in three ways:- Direct permissions — Explicitly granted to the user
- Tenant permissions — Inherited through tenant membership
- Role permissions — Inherited through role memberships
User Isolation
WhenENABLE_BACKEND_ACCESS_CONTROL=true, each user’s data is completely isolated:
- Database routing is automatic — Kùzu (graph) and LanceDB (vector) are configured per request via context variables
- Filesystem isolation — Each user gets their own database directory
- No cross-user access — Users can only access datasets they have explicit permissions for
Superuser Privileges
Users withis_superuser=True have additional privileges:
- Can manage other users, tenants, and roles
- Can access all datasets regardless of permissions
- Can perform administrative operations
Production Security — Superuser privileges should be carefully managed in production environments.