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

# users

> User management: get the default user, look up users, check existence, and create users

# User management

Helpers for resolving, looking up, and creating [users](/core-concepts/multi-user-mode/permissions-system/users). These live under `cognee.modules.users.methods` and are async, so `await` them.

```python theme={null}
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()

```python theme={null}
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](/core-concepts/multi-user-mode/permissions-system/users) for the environment variables.

### get\_user()

```python theme={null}
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()

```python theme={null}
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()

```python theme={null}
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.

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

### create\_user()

```python theme={null}
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 administrative privileges: manage other users/tenants/roles and access all datasets.                                                                                                      |
| `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. |

<Note>
  There is no global "list all users" helper. To enumerate the users in a [tenant](/core-concepts/multi-user-mode/permissions-system/tenants), 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`.
</Note>

## Examples

<AccordionGroup>
  <Accordion title="Check if a user exists before creating">
    `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`:

    ```python theme={null}
    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`:

    ```python theme={null}
    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)
    ```
  </Accordion>

  <Accordion title="Get the default user and pass it to operations">
    ```python theme={null}
    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.
  </Accordion>

  <Accordion title="Create an agent user owned by a parent">
    Pass `parent_user_id` so the parent user inherits permissions on datasets the agent creates:

    ```python theme={null}
    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](/core-concepts/multi-user-mode/permissions-system/users) for how parent/child permission inheritance works.
  </Accordion>
</AccordionGroup>