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 comes from DEFAULT_USER_PASSWORD. When that is unset the user is created with no password — usable by every SDK and CLI call, but not loginable over POST /api/v1/auth/login. There is no fallback password; see Default user credentials. 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.

Parameter	Type	Default	Notes
`user_id`	`UUID`	required	The 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).

Parameter	Type	Default	Notes
`user_email`	`str`	required	Email to look up.

get_user_id_by_email()

user_id = await get_user_id_by_email("alice@example.com", requester=user)

Returns the UUID of the user with that email, for sharing a dataset with them, but only when requester may see that user: the requester themselves, members of the requester’s tenants, or, for a requester in no tenant, users in no tenant. Otherwise it returns None, whether or not the address exists, so the lookup cannot be used to probe which emails are registered across tenants.

Parameter	Type	Default	Notes
`user_email`	`str`	required	Email to look up.
`requester`	`User`	required	The user performing the lookup; decides which users are visible.

Over HTTP, POST /api/v1/users/get-user-id applies the same rule with the authenticated caller as requester and returns 404 for any address outside that scope.

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.

Parameter	Type	Default	Notes
`email`	`str`	required	The new user’s email (unique).
`password`	`str`	required	Plaintext password; stored hashed.
`is_superuser`	`bool`	`False`	Grants superuser-only operations such as writing system settings. It does not grant tenant or role administration (that needs tenant ownership or the `manage_users` capability) or access to datasets without a grant.
`is_active`	`bool`	`True`	Whether the account is active. Inactive users cannot authenticate.
`is_verified`	`bool`	`False`	Whether the email is treated as verified.
`auto_login`	`bool`	`False`	When `True`, refreshes the user record after creation so it is ready for an immediate login flow.
`parent_user_id`	`Optional[UUID]`	`None`	UUID 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

Check if a user exists before creating

get_user_by_email() returns 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)

Get the default user and pass it to operations

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.

Create an agent user owned by a parent

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.

Reference

cognee.users

User management

Methods

get_default_user()

get_user()

get_user_by_email()

get_user_id_by_email()

create_user()

Examples

​User management

​Methods

​get_default_user()

​get_user()

​get_user_by_email()

​get_user_id_by_email()

​create_user()

​Examples

User management

Methods

get_default_user()

get_user()

get_user_by_email()

get_user_id_by_email()

create_user()

Examples