Skip to main content

​
User management

Helpers for resolving, looking up, and creating users. These live under cognee.modules.users.methods and are async, so await them. 
from cognee.modules.users.methods import (
    get_default_user,
    get_user,
    get_user_by_email,
    get_user_id_by_email,
    create_user,
)

​
Methods

​
get_default_user()

user = await get_default_user()
Returns the default user, creating it on first call if it does not exist yet. This is the same user Cognee resolves when you call remember(), recall(), etc. without passing user=. The default email comes from DEFAULT_USER_EMAIL (falls back to default_user@example.com); the password used at creation comes from DEFAULT_USER_PASSWORD (falls back to default_password). The auto-created default user is a superuser. See the Users concept page for the environment variables.

​
get_user()

user = await get_user(user_id)
Look up a user by UUID. Raises EntityNotFoundError if no user matches.
ParameterTypeDefaultNotes
user_idUUIDrequiredThe user’s UUID.

​
get_user_by_email()

user = await get_user_by_email("alice@example.com")
Look up a user by email. Returns the User object, or None if no user has that email — use this for existence checks (see below).
ParameterTypeDefaultNotes
user_emailstrrequiredEmail to look up.

​
get_user_id_by_email()

user_id = await get_user_id_by_email("alice@example.com")
Returns just the user’s UUID for a given email, or None if no such user exists. Lighter than get_user_by_email() when you only need the id.
ParameterTypeDefaultNotes
user_emailstrrequiredEmail to look up.

​
create_user()

user = await create_user(
    email="alice@example.com",
    password="s3cret",
)
Creates a new user. Raises fastapi_users.exceptions.UserAlreadyExists if a user with that email already exists.
ParameterTypeDefaultNotes
emailstrrequiredThe new user’s email (unique).
passwordstrrequiredPlaintext password; stored hashed.
is_superuserboolFalseGrants administrative privileges: manage other users/tenants/roles and access all datasets.
is_activeboolTrueWhether the account is active. Inactive users cannot authenticate.
is_verifiedboolFalseWhether the email is treated as verified.
auto_loginboolFalseWhen True, refreshes the user record after creation so it is ready for an immediate login flow.
parent_user_idOptional[UUID]NoneUUID of a parent user. Pass this when creating agent or service users so the parent automatically inherits permissions on any datasets those users create. Leave None for regular human users.
There is no global “list all users” helper. To enumerate the users in a tenant, use get_users_in_tenant(tenant_id, user) from cognee.modules.users.tenants.methods; the requesting user must have user-management permission on that tenant. It returns a list of dicts with id, email, and roles.

​
Examples

get_user_by_email() (and get_user_id_by_email()) return None when no user matches, so you can check existence without a try/except:
from cognee.modules.users.methods import get_user_by_email, create_user

email = "alice@example.com"

user = await get_user_by_email(email)
if user is None:
    user = await create_user(email=email, password="s3cret")
    print("created", user.id)
else:
    print("already exists", user.id)
If you prefer to attempt creation directly, catch UserAlreadyExists:
from fastapi_users.exceptions import UserAlreadyExists
from cognee.modules.users.methods import create_user, get_user_by_email

try:
    user = await create_user(email=email, password="s3cret")
except UserAlreadyExists:
    user = await get_user_by_email(email)

import cognee
from cognee.modules.users.methods import get_default_user

user = await get_default_user()

await cognee.add("Cognee turns data into memory.", user=user)
await cognee.cognify(user=user)
results = await cognee.search("What does Cognee do?", user=user)
Most top-level operations resolve the default user automatically when user= is omitted, so calling get_default_user() explicitly is only needed when you want the User object itself.
Pass parent_user_id so the parent user inherits permissions on datasets the agent creates:
from cognee.modules.users.methods import get_default_user, create_user

owner = await get_default_user()

agent = await create_user(
    email="agent@example.com",
    password="s3cret",
    parent_user_id=owner.id,
)
See Users for how parent/child permission inheritance works.