AuthHandler

pybticino.auth.AuthHandler

Handles asynchronous authentication and token management for the BTicino API.

This class manages the OAuth2 password grant flow to obtain access and refresh tokens. It automatically handles token expiration and refreshing. It uses an aiohttp.ClientSession for making HTTP requests.

Attributes:

Name	Type	Description
_username	str	The user's email address for authentication.
_password	str	The user's password for authentication.
_client_id	str	The client ID for the API application.
_client_secret	str	The client secret for the API application.
_scope	str	The requested scope for the access token.
_app_version	str	The application version string sent during auth.
_access_token	Optional[str]	The current access token.
_refresh_token	Optional[str]	The current refresh token.
_token_expires_at	Optional[float]	The timestamp when the access token expires.
_session	Optional[ClientSession]	The HTTP client session.
_managed_session	bool	True if the session was created internally and should be closed by this handler, False otherwise.

__init__

__init__(username: str, password: str, scope: str = DEFAULT_SCOPE, app_version: str = DEFAULT_APP_VERSION, session: ClientSession | None = None, token_callback: Callable[[dict], Awaitable[None]] | None = None) -> None

Initialize the asynchronous authentication handler.

Parameters:

Name	Type	Description	Default
username	str	The user's email address (BTicino/Netatmo account).	required
password	str	The user's password.	required
scope	str	The requested OAuth scope. Defaults to DEFAULT_SCOPE.	DEFAULT_SCOPE
app_version	str	The application version string. Defaults to DEFAULT_APP_VERSION.	DEFAULT_APP_VERSION
session	Optional[ClientSession]	An optional existing aiohttp.ClientSession to use for requests. If None, a new session will be created and managed internally.	None
token_callback	Callable[[dict], Awaitable[None]] | None	An optional async callback invoked whenever tokens change (after authentication or refresh). Receives a dict with keys: access_token, refresh_token, expires_at. Useful for persisting tokens across restarts.	None

close_session async

close_session() -> None

Close the aiohttp.ClientSession if it was created internally.

If the session was provided externally during initialization, this method does nothing.

set_tokens

set_tokens(access_token: str, refresh_token: str, expires_at: float | None = None) -> None

Inject existing tokens, e.g. restored from persistent storage.

This allows callers to restore a previous session without performing a full username/password authentication.

Parameters:

Name	Type	Description	Default
access_token	str	A previously obtained access token.	required
refresh_token	str	A previously obtained refresh token.	required
expires_at	float | None	The timestamp when the access token expires. If None, the token will be considered expired and a refresh will be attempted on the next get_access_token() call.	None

get_access_token async

get_access_token() -> str

Return a valid access token, automatically authenticating or refreshing.

This method checks if the current token is valid. If it's expired or nearing expiration, it attempts to refresh it using the refresh token. If refreshing fails or no refresh token is available, it performs a full authentication using the username and password.

Returns:

Name	Type	Description
str	str	A valid access token.

Raises:

Type	Description
AuthError	If authentication or token refresh fails persistently.

authenticate async

authenticate() -> None

Perform the initial authentication using username and password.

This method makes a POST request to the token endpoint with the 'password' grant type to obtain the initial access and refresh tokens. It stores the tokens and their expiration time internally.

Raises:

Type	Description
AuthError	If authentication fails due to invalid credentials, network errors, timeouts, or unexpected issues.
ApiError	If the API returns a non-success status code other than common authentication failures handled by AuthError.