Skip to main content

​
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.
Default user behavior — When no user is specified, Cognee uses a default user with email “[email protected]” for development and testing.

​
User Authentication

Users authenticate through email and password.

​
User Management

Users can:
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 password
  • tenant_id: ID of the tenant the user belongs to (nullable)
  • is_active: Whether the user account is active
  • is_verified: Whether the user’s email is verified
  • is_superuser: Whether the user has superuser privileges
  • create_user(email, password, tenant_id=None, is_superuser=False): Creates a new user with specified credentials
  • Default user behavior: System creates “[email protected]” if no user exists
  • DEFAULT_USER_EMAIL: Override default user email (default: “[email protected]”)
  • DEFAULT_USER_PASSWORD: Override default user password (default: “default_password”)
  • REQUIRE_AUTHENTICATION: Enforce authentication on HTTP endpoints (default: “true”)
  • FASTAPI_USERS_RESET_PASSWORD_TOKEN_SECRET: Secret for password reset tokens
  • FASTAPI_USERS_VERIFICATION_TOKEN_SECRET: Secret for email verification tokens

​
User Permissions

Users can receive permissions in three ways:
  1. Direct permissions — Explicitly granted to the user
  2. Tenant permissions — Inherited through tenant membership
  3. Role permissions — Inherited through role memberships
The system calculates effective permissions by combining all three sources, giving users the union of their direct permissions, tenant-level permissions, and role-level permissions.

​
User Isolation

When ENABLE_BACKEND_ACCESS_CONTROL=true, each user’s data is completely isolated:
  • Database routing is automatic — Databases are configured per request via context variables and with the help of Dataset Database Handlers
  • Filesystem isolation — Each user gets their own database directory
  • No unauthorized access — Users can only access datasets they have explicit permissions for

​
Superuser Privileges

Users with is_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.

Tenants

Learn about organization-level access control

Roles

Understand role-based permissions within tenants