Users

Manage user accounts: profile updates, password changes, registration, and logout.

UsersClient

Sub-client for user account management endpoints.

Accessed via HomeboxClient.users.

Source code in homebox/client.py

class UsersClient:
    """Sub-client for user account management endpoints.

    Accessed via ``HomeboxClient.users``.
    """

    def __init__(self, client: HomeboxClient):
        """Initialise the users sub-client with the shared root client."""
        self.client = client

    def change_password(self, data: ChangePassword):
        """Change the current user's password.

        Args:
            data: Password change payload containing ``current`` and ``new``
                password strings.
        """
        self.client._request("put", "/v1/users/change-password", data=data.model_dump())

    def user_logout(self):
        """Invalidate the current session token on the server side."""
        self.client._request("post", "/v1/users/logout")

    def user_token_refresh(self) -> TokenResponse:
        """Refresh the current Bearer token and return a new one.

        Returns:
            TokenResponse: New token with updated expiry.
        """
        return TokenResponse(**self.client._request("get", "/v1/users/refresh"))

    def oidc_login(self, timeout: float | None = None) -> str | None:
        """Initiate OIDC login and return the provider redirect URL.

        Args:
            timeout: Optional request timeout in seconds.

        Returns:
            str | None: Location header value for the OIDC redirect, if
                present.
        """
        response = requests.get(
            f"{self.client.base_url}/v1/users/login/oidc",
            headers=self.client.headers.copy(),
            allow_redirects=False,
            timeout=timeout,
        )
        response.raise_for_status()
        return response.headers.get("Location")

    def oidc_callback(self, code: str, state: str, timeout: float | None = None) -> str | None:
        """Call the OIDC callback endpoint and return the redirect location.

        Args:
            code: Authorization code received from the OIDC provider.
            state: State value returned by the OIDC provider.
            timeout: Optional request timeout in seconds.

        Returns:
            str | None: Location header value returned by Homebox.
        """
        params = {"code": code, "state": state}
        response = requests.get(
            f"{self.client.base_url}/v1/users/login/oidc/callback",
            params=params,
            headers=self.client.headers.copy(),
            allow_redirects=False,
            timeout=timeout,
        )
        response.raise_for_status()
        return response.headers.get("Location")

    def register_new_user(self, data: UserRegistration):
        """Register a new user account.

        Requires either open registration to be enabled on the server, or a
        valid group invitation token included in ``data``.

        Args:
            data: Registration payload containing ``name``, ``email``,
                ``password``, and an optional invitation ``token``.
        """
        self.client._request("post", "/v1/users/register", data=data.model_dump())

    def get_user_self(self) -> UserOut:
        """Return the profile of the currently authenticated user.

        Returns:
            UserOut: User details including ID, name, email, group association,
                and role flags.
        """
        response = self.client._request("get", "/v1/users/self")
        payload = response.get("item", response)
        return UserOut(**payload)

    def update_account(self, data: UserUpdate) -> UserUpdate:
        """Update the current user's profile information.

        Args:
            data: Fields to update (``name`` and ``email``).

        Returns:
            UserUpdate: The updated profile data as echoed by the server.
        """
        response = self.client._request("put", "/v1/users/self", data=data.model_dump())
        payload = response.get("item", response)
        return UserUpdate(**payload)

    def get_user_settings(self) -> UserSettings:
        """Return settings for the currently authenticated user.

        Returns:
            UserSettings: Arbitrary per-user settings key/value object.
        """
        response = self.client._request("get", "/v1/users/self/settings")
        payload = response.get("item", response)
        return UserSettings(**payload)

    def update_user_settings(self, data: UserSettings | dict[str, Any]) -> UserSettings:
        """Update settings for the currently authenticated user.

        Args:
            data: Arbitrary key/value settings payload.

        Returns:
            UserSettings: Updated user settings returned by the server.
        """
        payload = data.model_dump(exclude_none=True) if isinstance(data, UserSettings) else data
        response = self.client._request("put", "/v1/users/self/settings", data=payload)
        wrapped = response.get("item", response)
        return UserSettings(**wrapped)

    def delete_account(self):
        """Permanently delete the current user's account.

        This action is irreversible and will also remove the user from their
        group.
        """
        self.client._request("delete", "/v1/users/self")

__init__

__init__(client: HomeboxClient)

Initialise the users sub-client with the shared root client.

Source code in homebox/client.py

def __init__(self, client: HomeboxClient):
    """Initialise the users sub-client with the shared root client."""
    self.client = client

change_password

change_password(data: ChangePassword)

Change the current user's password.

Parameters:

Name	Type	Description	Default
data	ChangePassword	Password change payload containing current and new password strings.	required

Source code in homebox/client.py

def change_password(self, data: ChangePassword):
    """Change the current user's password.

    Args:
        data: Password change payload containing ``current`` and ``new``
            password strings.
    """
    self.client._request("put", "/v1/users/change-password", data=data.model_dump())

user_logout

user_logout()

Invalidate the current session token on the server side.

Source code in homebox/client.py

def user_logout(self):
    """Invalidate the current session token on the server side."""
    self.client._request("post", "/v1/users/logout")

user_token_refresh

user_token_refresh() -> TokenResponse

Refresh the current Bearer token and return a new one.

Returns:

Name	Type	Description
TokenResponse	TokenResponse	New token with updated expiry.

Source code in homebox/client.py

def user_token_refresh(self) -> TokenResponse:
    """Refresh the current Bearer token and return a new one.

    Returns:
        TokenResponse: New token with updated expiry.
    """
    return TokenResponse(**self.client._request("get", "/v1/users/refresh"))

oidc_login

oidc_login(timeout: float | None = None) -> str | None

Initiate OIDC login and return the provider redirect URL.

Parameters:

Name	Type	Description	Default
timeout	float | None	Optional request timeout in seconds.	None

Returns:

Type	Description
str | None	str | None: Location header value for the OIDC redirect, if present.

Source code in homebox/client.py

def oidc_login(self, timeout: float | None = None) -> str | None:
    """Initiate OIDC login and return the provider redirect URL.

    Args:
        timeout: Optional request timeout in seconds.

    Returns:
        str | None: Location header value for the OIDC redirect, if
            present.
    """
    response = requests.get(
        f"{self.client.base_url}/v1/users/login/oidc",
        headers=self.client.headers.copy(),
        allow_redirects=False,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.headers.get("Location")

oidc_callback

oidc_callback(code: str, state: str, timeout: float | None = None) -> str | None

Call the OIDC callback endpoint and return the redirect location.

Parameters:

Name	Type	Description	Default
code	str	Authorization code received from the OIDC provider.	required
state	str	State value returned by the OIDC provider.	required
timeout	float | None	Optional request timeout in seconds.	None

Returns:

Type	Description
str | None	str | None: Location header value returned by Homebox.

Source code in homebox/client.py

def oidc_callback(self, code: str, state: str, timeout: float | None = None) -> str | None:
    """Call the OIDC callback endpoint and return the redirect location.

    Args:
        code: Authorization code received from the OIDC provider.
        state: State value returned by the OIDC provider.
        timeout: Optional request timeout in seconds.

    Returns:
        str | None: Location header value returned by Homebox.
    """
    params = {"code": code, "state": state}
    response = requests.get(
        f"{self.client.base_url}/v1/users/login/oidc/callback",
        params=params,
        headers=self.client.headers.copy(),
        allow_redirects=False,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.headers.get("Location")

register_new_user

register_new_user(data: UserRegistration)

Register a new user account.

Requires either open registration to be enabled on the server, or a valid group invitation token included in data.

Parameters:

Name	Type	Description	Default
data	UserRegistration	Registration payload containing name, email, password, and an optional invitation token.	required

Source code in homebox/client.py

def register_new_user(self, data: UserRegistration):
    """Register a new user account.

    Requires either open registration to be enabled on the server, or a
    valid group invitation token included in ``data``.

    Args:
        data: Registration payload containing ``name``, ``email``,
            ``password``, and an optional invitation ``token``.
    """
    self.client._request("post", "/v1/users/register", data=data.model_dump())

get_user_self

get_user_self() -> UserOut

Return the profile of the currently authenticated user.

Returns:

Name	Type	Description
UserOut	UserOut	User details including ID, name, email, group association, and role flags.

Source code in homebox/client.py

def get_user_self(self) -> UserOut:
    """Return the profile of the currently authenticated user.

    Returns:
        UserOut: User details including ID, name, email, group association,
            and role flags.
    """
    response = self.client._request("get", "/v1/users/self")
    payload = response.get("item", response)
    return UserOut(**payload)

update_account

update_account(data: UserUpdate) -> UserUpdate

Update the current user's profile information.

Parameters:

Name	Type	Description	Default
data	UserUpdate	Fields to update (name and email).	required

Returns:

Name	Type	Description
UserUpdate	UserUpdate	The updated profile data as echoed by the server.

Source code in homebox/client.py

def update_account(self, data: UserUpdate) -> UserUpdate:
    """Update the current user's profile information.

    Args:
        data: Fields to update (``name`` and ``email``).

    Returns:
        UserUpdate: The updated profile data as echoed by the server.
    """
    response = self.client._request("put", "/v1/users/self", data=data.model_dump())
    payload = response.get("item", response)
    return UserUpdate(**payload)

get_user_settings

get_user_settings() -> UserSettings

Return settings for the currently authenticated user.

Returns:

Name	Type	Description
UserSettings	UserSettings	Arbitrary per-user settings key/value object.

Source code in homebox/client.py

def get_user_settings(self) -> UserSettings:
    """Return settings for the currently authenticated user.

    Returns:
        UserSettings: Arbitrary per-user settings key/value object.
    """
    response = self.client._request("get", "/v1/users/self/settings")
    payload = response.get("item", response)
    return UserSettings(**payload)

update_user_settings

update_user_settings(data: UserSettings | dict[str, Any]) -> UserSettings

Update settings for the currently authenticated user.

Parameters:

Name	Type	Description	Default
data	UserSettings | dict[str, Any]	Arbitrary key/value settings payload.	required

Returns:

Name	Type	Description
UserSettings	UserSettings	Updated user settings returned by the server.

Source code in homebox/client.py

def update_user_settings(self, data: UserSettings | dict[str, Any]) -> UserSettings:
    """Update settings for the currently authenticated user.

    Args:
        data: Arbitrary key/value settings payload.

    Returns:
        UserSettings: Updated user settings returned by the server.
    """
    payload = data.model_dump(exclude_none=True) if isinstance(data, UserSettings) else data
    response = self.client._request("put", "/v1/users/self/settings", data=payload)
    wrapped = response.get("item", response)
    return UserSettings(**wrapped)

delete_account

delete_account()

Permanently delete the current user's account.

This action is irreversible and will also remove the user from their group.

Source code in homebox/client.py

def delete_account(self):
    """Permanently delete the current user's account.

    This action is irreversible and will also remove the user from their
    group.
    """
    self.client._request("delete", "/v1/users/self")