users

Client for user management and admin user endpoints.

Classes

UsersClient

UsersClient(client: OWUIClientBase)

Bases: ResourceBase

Client for User management endpoints.

This client handles operations related to user accounts, profiles, settings, permissions, and groups.

Used by:

• Code Reference client Classes OpenWebUI Attributes users

Source code in src/owui_client/client_base.py

def __init__(self, client: OWUIClientBase):
    self._client = client

Functions

get_users

get_users(
    query: Optional[str] = None,
    order_by: Optional[str] = None,
    direction: Optional[str] = None,
    page: Optional[int] = 1,
) -> UserGroupIdsListResponse

Get users with pagination and filtering.

This endpoint is typically used by admins to manage users. Note: While the backend model layer supports complex filtering (e.g., by channel_id, user_ids), this endpoint currently only exposes query, order_by, direction, and page.

Parameters:

Name	Type	Description	Default
query	Optional[str]	Search query for name or email.	None
order_by	Optional[str]	Field to order by (e.g., 'name', 'email', 'created_at', 'last_active_at', 'updated_at', 'role').	None
direction	Optional[str]	Sort direction ('asc' or 'desc').	None
page	Optional[int]	Page number (starts at 1).	1

Returns:

Type	Description
UserGroupIdsListResponse	UserGroupIdsListResponse: List of users with group IDs and total count.

Source code in src/owui_client/routers/users.py

async def get_users(
    self,
    query: Optional[str] = None,
    order_by: Optional[str] = None,
    direction: Optional[str] = None,
    page: Optional[int] = 1,
) -> UserGroupIdsListResponse:
    """
    Get users with pagination and filtering.

    This endpoint is typically used by admins to manage users.
    Note: While the backend model layer supports complex filtering (e.g., by channel_id, user_ids),
    this endpoint currently only exposes query, order_by, direction, and page.

    Args:
        query: Search query for name or email.
        order_by: Field to order by (e.g., 'name', 'email', 'created_at', 'last_active_at', 'updated_at', 'role').
        direction: Sort direction ('asc' or 'desc').
        page: Page number (starts at 1).

    Returns:
        `UserGroupIdsListResponse`: List of users with group IDs and total count.
    """
    params = {}
    if query:
        params["query"] = query
    if order_by:
        params["order_by"] = order_by
    if direction:
        params["direction"] = direction
    if page:
        params["page"] = page

    return await self._request(
        "GET",
        "/v1/users/",
        model=UserGroupIdsListResponse,
        params=params,
    )

get_all_users

get_all_users() -> UserInfoListResponse

Get all users (abbreviated info).

Retrieves a list of all users with basic information. This is an admin-only endpoint.

Returns:

Type	Description
UserInfoListResponse	UserInfoListResponse: List of all users with basic info.

Source code in src/owui_client/routers/users.py

async def get_all_users(self) -> UserInfoListResponse:
    """
    Get all users (abbreviated info).

    Retrieves a list of all users with basic information.
    This is an admin-only endpoint.

    Returns:
        `UserInfoListResponse`: List of all users with basic info.
    """
    return await self._request(
        "GET",
        "/v1/users/all",
        model=UserInfoListResponse,
    )

search_users

search_users(
    query: Optional[str] = None,
) -> UserIdNameListResponse

Search users by query (name or email).

Searches for users matching the query string. Returns the first page of results (limit 30).

Parameters:

Name	Type	Description	Default
query	Optional[str]	Search query string.	None

Returns:

Type	Description
UserIdNameListResponse	UserIdNameListResponse: List of users (ID and name) matching the query.

Source code in src/owui_client/routers/users.py

async def search_users(self, query: Optional[str] = None) -> UserIdNameListResponse:
    """
    Search users by query (name or email).

    Searches for users matching the query string.
    Returns the first page of results (limit 30).

    Args:
        query: Search query string.

    Returns:
        `UserIdNameListResponse`: List of users (ID and name) matching the query.
    """
    params = {}
    if query:
        params["query"] = query

    return await self._request(
        "GET",
        "/v1/users/search",
        model=UserIdNameListResponse,
        params=params,
    )

get_user_groups

get_user_groups() -> List[GroupModel]

Get the groups the current user belongs to.

Returns:

Type	Description
List[GroupModel]	List[GroupModel]: List of groups the user is a member of.

Source code in src/owui_client/routers/users.py

async def get_user_groups(self) -> List[GroupModel]:
    """
    Get the groups the current user belongs to.

    Returns:
        List[GroupModel]: List of groups the user is a member of.
    """
    return await self._request(
        "GET",
        "/v1/users/groups",
        model=GroupModel,
    )

get_user_permissions

get_user_permissions() -> Dict

Get the current user's permissions.

Returns:

Name	Type	Description
Dict	Dict	Dictionary of user permissions (workspace, sharing, chat, features).

Source code in src/owui_client/routers/users.py

async def get_user_permissions(self) -> Dict:
    """
    Get the current user's permissions.

    Returns:
        Dict: Dictionary of user permissions (workspace, sharing, chat, features).
    """
    return await self._request(
        "GET",
        "/v1/users/permissions",
    )

get_default_user_permissions

get_default_user_permissions() -> UserPermissions

Get the default user permissions.

This is an admin-only endpoint.

Returns:

Type	Description
UserPermissions	UserPermissions: Default user permissions.

Source code in src/owui_client/routers/users.py

async def get_default_user_permissions(self) -> UserPermissions:
    """
    Get the default user permissions.

    This is an admin-only endpoint.

    Returns:
        `UserPermissions`: Default user permissions.
    """
    return await self._request(
        "GET",
        "/v1/users/default/permissions",
        model=UserPermissions,
    )

update_default_user_permissions

update_default_user_permissions(
    permissions: UserPermissions,
) -> UserPermissions

Update the default user permissions.

This is an admin-only endpoint.

Parameters:

Name	Type	Description	Default
permissions	UserPermissions	The new default permissions.	required

Returns:

Type	Description
UserPermissions	UserPermissions: The updated default permissions.

Source code in src/owui_client/routers/users.py

async def update_default_user_permissions(
    self, permissions: UserPermissions
) -> UserPermissions:
    """
    Update the default user permissions.

    This is an admin-only endpoint.

    Args:
        permissions: The new default permissions.

    Returns:
        `UserPermissions`: The updated default permissions.
    """
    # Note: The backend returns the dict directly, but we can model validate it back to UserPermissions
    return await self._request(
        "POST",
        "/v1/users/default/permissions",
        model=UserPermissions,
        json=permissions.model_dump(exclude_none=True, by_alias=True),
    )

get_default_user_permission_defaults

get_default_user_permission_defaults() -> UserPermissions

Get the built-in default user permission set.

Returns the hardcoded DEFAULT_USER_PERMISSIONS shipped with Open WebUI, unaffected by the currently configured defaults returned by get_default_user_permissions. Intended for a "reset permissions to defaults" workflow.

This is an admin-only endpoint.

Returns:

Type	Description
UserPermissions	UserPermissions: The built-in default permissions.

Source code in src/owui_client/routers/users.py

async def get_default_user_permission_defaults(self) -> UserPermissions:
    """
    Get the built-in default user permission set.

    Returns the hardcoded `DEFAULT_USER_PERMISSIONS` shipped with Open WebUI,
    unaffected by the currently configured defaults returned by
    `get_default_user_permissions`. Intended for a "reset permissions to
    defaults" workflow.

    This is an admin-only endpoint.

    Returns:
        `UserPermissions`: The built-in default permissions.
    """
    return await self._request(
        "GET",
        "/v1/users/default/permissions/defaults",
        model=UserPermissions,
    )

get_user_settings

get_user_settings() -> Optional[UserSettings]

Get the current session user's settings.

Returns:

Type	Description
Optional[UserSettings]	Optional[UserSettings]: User settings if available.

Source code in src/owui_client/routers/users.py

async def get_user_settings(self) -> Optional[UserSettings]:
    """
    Get the current session user's settings.

    Returns:
        Optional[UserSettings]: User settings if available.
    """
    return await self._request(
        "GET",
        "/v1/users/user/settings",
        model=Optional[UserSettings],
    )

update_user_settings

update_user_settings(
    settings: UserSettings,
) -> UserSettings

Update the current session user's settings.

Parameters:

Name	Type	Description	Default
settings	UserSettings	The new user settings.	required

Returns:

Type	Description
UserSettings	UserSettings: The updated user settings.

Source code in src/owui_client/routers/users.py

async def update_user_settings(self, settings: UserSettings) -> UserSettings:
    """
    Update the current session user's settings.

    Args:
        settings: The new user settings.

    Returns:
        `UserSettings`: The updated user settings.
    """
    return await self._request(
        "POST",
        "/v1/users/user/settings/update",
        model=UserSettings,
        json=settings.model_dump(exclude_none=True),
    )

get_user_status

get_user_status() -> UserModel

Get the current session user's status.

Returns:

Type	Description
UserModel	UserModel: The user model which includes status fields.

Source code in src/owui_client/routers/users.py

async def get_user_status(self) -> UserModel:
    """
    Get the current session user's status.

    Returns:
        `UserModel`: The user model which includes status fields.
    """
    return await self._request(
        "GET",
        "/v1/users/user/status",
        model=UserModel,
    )

update_user_status

update_user_status(status: UserStatus) -> UserModel

Update the current session user's status.

Parameters:

Name	Type	Description	Default
status	UserStatus	The new user status.	required

Returns:

Type	Description
UserModel	UserModel: The updated user model.

Source code in src/owui_client/routers/users.py

async def update_user_status(self, status: UserStatus) -> UserModel:
    """
    Update the current session user's status.

    Args:
        status: The new user status.

    Returns:
        `UserModel`: The updated user model.
    """
    return await self._request(
        "POST",
        "/v1/users/user/status/update",
        model=UserModel,
        json=status.model_dump(exclude_none=True),
    )

get_user_info

get_user_info() -> Optional[Dict[str, Any]]

Get the current session user's info.

This returns extra info stored in the user's 'info' JSON field.

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: User info dictionary.

Source code in src/owui_client/routers/users.py

async def get_user_info(self) -> Optional[Dict[str, Any]]:
    """
    Get the current session user's info.

    This returns extra info stored in the user's 'info' JSON field.

    Returns:
        Optional[Dict[str, Any]]: User info dictionary.
    """
    return await self._request(
        "GET",
        "/v1/users/user/info",
    )

update_user_info

update_user_info(
    info: Dict[str, Any],
) -> Optional[Dict[str, Any]]

Update the current session user's info.

Merges the provided dictionary with the existing info.

Parameters:

Name	Type	Description	Default
info	Dict[str, Any]	The new info dictionary to merge/update.	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: The updated user info dictionary.

Source code in src/owui_client/routers/users.py

async def update_user_info(self, info: Dict[str, Any]) -> Optional[Dict[str, Any]]:
    """
    Update the current session user's info.

    Merges the provided dictionary with the existing info.

    Args:
        info: The new info dictionary to merge/update.

    Returns:
        Optional[Dict[str, Any]]: The updated user info dictionary.
    """
    return await self._request(
        "POST",
        "/v1/users/user/info/update",
        json=info,
    )

get_user_variables

get_user_variables() -> UserVariablesResponse

Get the calling (session) user's variables.

Variables are template substitutions available in system prompts via {{ user.variables.KEY }}. The response is normalized to dict[str, str].

Returns:

Type	Description
UserVariablesResponse	UserVariablesResponse: The user's variables (string keys/values).

Source code in src/owui_client/routers/users.py

async def get_user_variables(self) -> UserVariablesResponse:
    """
    Get the calling (session) user's variables.

    Variables are template substitutions available in system prompts via
    `{{ user.variables.KEY }}`. The response is normalized to `dict[str, str]`.

    Returns:
        `UserVariablesResponse`: The user's variables (string keys/values).
    """
    return await self._request(
        "GET",
        "/v1/users/user/variables",
        model=UserVariablesResponse,
    )

update_user_variables

update_user_variables(
    variables: Dict[str, str],
) -> UserVariablesResponse

Update the calling (session) user's variables.

Replaces the user's stored variables with the supplied mapping. Keys must match ^[a-z][a-z0-9_]*$ and values must be strings; the backend rejects invalid input with HTTP 400.

Parameters:

Name	Type	Description	Default
variables	Dict[str, str]	Mapping of variable key to string value.	required

Returns:

Type	Description
UserVariablesResponse	UserVariablesResponse: The normalized variables now stored for
UserVariablesResponse	the user.

Source code in src/owui_client/routers/users.py

async def update_user_variables(
    self, variables: Dict[str, str]
) -> UserVariablesResponse:
    """
    Update the calling (session) user's variables.

    Replaces the user's stored variables with the supplied mapping. Keys
    must match `^[a-z][a-z0-9_]*$` and values must be strings; the backend
    rejects invalid input with HTTP 400.

    Args:
        variables: Mapping of variable key to string value.

    Returns:
        `UserVariablesResponse`: The normalized variables now stored for
        the user.
    """
    form = UserVariablesForm(variables=variables)
    return await self._request(
        "POST",
        "/v1/users/user/variables/update",
        model=UserVariablesResponse,
        json=form.model_dump(),
    )

get_user_usage

get_user_usage(
    days: Optional[int] = None,
    start_date: Optional[int] = None,
    end_date: Optional[int] = None,
) -> UserUsageResponse

Get usage info for the calling (session) user.

Returns aggregate token/message totals, daily/weekly/cumulative activity heatmaps, derived insights, and top models/tools over a time window.

The period is determined by the first available of: an explicit start_date/end_date window, a days count back from end_date (or now), or a default spanning up to two years from the user's creation date. When days is given it must be between 7 and 732.

Parameters:

Name	Type	Description	Default
days	Optional[int]	Number of days to cover (must be between 7 and 732). Used only if start_date is not given.	None
start_date	Optional[int]	Period start as a Unix epoch timestamp (seconds).	None
end_date	Optional[int]	Period end as a Unix epoch timestamp (seconds); defaults to now.	None

Returns:

Type	Description
UserUsageResponse	UserUsageResponse: The usage report for the user.

Source code in src/owui_client/routers/users.py

async def get_user_usage(
    self,
    days: Optional[int] = None,
    start_date: Optional[int] = None,
    end_date: Optional[int] = None,
) -> UserUsageResponse:
    """
    Get usage info for the calling (session) user.

    Returns aggregate token/message totals, daily/weekly/cumulative activity
    heatmaps, derived insights, and top models/tools over a time window.

    The period is determined by the first available of: an explicit
    `start_date`/`end_date` window, a `days` count back from `end_date`
    (or now), or a default spanning up to two years from the user's
    creation date. When `days` is given it must be between 7 and 732.

    Args:
        days: Number of days to cover (must be between 7 and 732). Used
            only if `start_date` is not given.
        start_date: Period start as a Unix epoch timestamp (seconds).
        end_date: Period end as a Unix epoch timestamp (seconds);
            defaults to now.

    Returns:
        `UserUsageResponse`: The usage report for the user.
    """
    params = {}
    if days is not None:
        params["days"] = days
    if start_date is not None:
        params["start_date"] = start_date
    if end_date is not None:
        params["end_date"] = end_date

    return await self._request(
        "GET",
        "/v1/users/usage",
        model=UserUsageResponse,
        params=params,
    )

get_user_by_id

get_user_by_id(user_id: str) -> UserActiveResponse

Get a user by ID.

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user.	required

Returns:

Type	Description
UserActiveResponse	UserActiveResponse: User info including active status.

Source code in src/owui_client/routers/users.py

async def get_user_by_id(self, user_id: str) -> UserActiveResponse:
    """
    Get a user by ID.

    Args:
        user_id: The ID of the user.

    Returns:
        `UserActiveResponse`: User info including active status.
    """
    return await self._request(
        "GET",
        f"/v1/users/{user_id}",
        model=UserActiveResponse,
    )

update_user_by_id

update_user_by_id(
    user_id: str, form_data: UserUpdateForm
) -> UserModel

Update a user by ID.

This is an admin-only endpoint. It can be used to update user details including role and password.

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user to update.	required
form_data	UserUpdateForm	The update form data.	required

Returns:

Type	Description
UserModel	UserModel: The updated user model.

Source code in src/owui_client/routers/users.py

async def update_user_by_id(
    self, user_id: str, form_data: UserUpdateForm
) -> UserModel:
    """
    Update a user by ID.

    This is an admin-only endpoint. It can be used to update user details including
    role and password.

    Args:
        user_id: The ID of the user to update.
        form_data: The update form data.

    Returns:
        `UserModel`: The updated user model.
    """
    return await self._request(
        "POST",
        f"/v1/users/{user_id}/update",
        model=UserModel,
        json=form_data.model_dump(exclude_none=True),
    )

delete_user_by_id

delete_user_by_id(user_id: str) -> bool

Delete a user by ID.

This is an admin-only endpoint.

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user to delete.	required

Returns:

Name	Type	Description
bool	bool	True if successful.

Source code in src/owui_client/routers/users.py

async def delete_user_by_id(self, user_id: str) -> bool:
    """
    Delete a user by ID.

    This is an admin-only endpoint.

    Args:
        user_id: The ID of the user to delete.

    Returns:
        bool: True if successful.
    """
    return await self._request(
        "DELETE",
        f"/v1/users/{user_id}",
        model=bool,
    )

get_user_oauth_sessions_by_id

get_user_oauth_sessions_by_id(
    user_id: str,
) -> List[OAuthSessionModel]

Get OAuth sessions for a user by ID.

This is an admin-only endpoint.

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user.	required

Returns:

Type	Description
List[OAuthSessionModel]	List[OAuthSessionModel]: List of OAuth sessions.

Source code in src/owui_client/routers/users.py

async def get_user_oauth_sessions_by_id(
    self, user_id: str
) -> List[OAuthSessionModel]:
    """
    Get OAuth sessions for a user by ID.

    This is an admin-only endpoint.

    Args:
        user_id: The ID of the user.

    Returns:
        List[OAuthSessionModel]: List of OAuth sessions.
    """
    return await self._request(
        "GET",
        f"/v1/users/{user_id}/oauth/sessions",
        model=OAuthSessionModel,
    )

get_user_profile_image_by_id

get_user_profile_image_by_id(user_id: str) -> bytes

Get a user's profile image by ID.

Returns the image content (bytes).

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user.	required

Returns:

Name	Type	Description
bytes	bytes	Image content.

Source code in src/owui_client/routers/users.py

async def get_user_profile_image_by_id(self, user_id: str) -> bytes:
    """
    Get a user's profile image by ID.

    Returns the image content (bytes).

    Args:
        user_id: The ID of the user.

    Returns:
        bytes: Image content.
    """
    return await self._request(
        "GET",
        f"/v1/users/{user_id}/profile/image",
        model=bytes,
        follow_redirects=True,
    )

get_user_active_status_by_id

get_user_active_status_by_id(
    user_id: str,
) -> Dict[str, bool]

Get a user's active status by ID.

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user.	required

Returns:

Type	Description
Dict[str, bool]	Dict[str, bool]: Dictionary with 'active' status key.

Source code in src/owui_client/routers/users.py

async def get_user_active_status_by_id(self, user_id: str) -> Dict[str, bool]:
    """
    Get a user's active status by ID.

    Args:
        user_id: The ID of the user.

    Returns:
        Dict[str, bool]: Dictionary with 'active' status key.
    """
    return await self._request(
        "GET",
        f"/v1/users/{user_id}/active",
    )

get_user_groups_by_id

get_user_groups_by_id(user_id: str) -> List[GroupModel]

Get the groups a user belongs to by user ID.

This is an admin-only endpoint.

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user.	required

Returns:

Type	Description
List[GroupModel]	List[GroupModel]: List of groups.

Source code in src/owui_client/routers/users.py

async def get_user_groups_by_id(self, user_id: str) -> List[GroupModel]:
    """
    Get the groups a user belongs to by user ID.

    This is an admin-only endpoint.

    Args:
        user_id: The ID of the user.

    Returns:
        List[GroupModel]: List of groups.
    """
    return await self._request(
        "GET",
        f"/v1/users/{user_id}/groups",
        model=GroupModel,
    )

get_user_preview_by_id

get_user_preview_by_id(user_id: str) -> UserPreview

Get a preview of the resources a user can access.

Returns a summary showing which models, knowledge bases, and tools the specified user can access across all groups they belong to. Useful for administrators to audit a user's effective permissions.

This is an admin-only endpoint.

Parameters:

Name	Type	Description	Default
user_id	str	The ID of the user to preview.	required

Returns:

Type	Description
UserPreview	UserPreview: The user preview payload, including the user, their
UserPreview	groups, and the accessible models/knowledge/tools with totals.

Source code in src/owui_client/routers/users.py

async def get_user_preview_by_id(self, user_id: str) -> UserPreview:
    """
    Get a preview of the resources a user can access.

    Returns a summary showing which models, knowledge bases, and tools the
    specified user can access across all groups they belong to. Useful for
    administrators to audit a user's effective permissions.

    This is an admin-only endpoint.

    Args:
        user_id: The ID of the user to preview.

    Returns:
        `UserPreview`: The user preview payload, including the user, their
        groups, and the accessible models/knowledge/tools with totals.
    """
    return await self._request(
        "GET",
        f"/v1/users/{user_id}/preview",
        model=UserPreview,
    )