Authentication

Binds to the Tado API v2.

Handles OAuth2 device-code authentication (see login_device_flow() and device_activation()) and exposes methods to read and control your Tado home, zones, schedules and energy data.

__init__(saved_refresh_token=None, token_file_path=None)

Create a Tado API client and establish authentication.

If saved_refresh_token is given, or a refresh token can be loaded from token_file_path, it is used to refresh the access token via refresh_auth(). If that succeeds, the client finalizes setup with device_ready(). Otherwise, the OAuth2 device-code login flow is started via login_device_flow(); the caller must then complete it (e.g. by calling device_activation()).

Parameters:

Name	Type	Description	Default
saved_refresh_token	str	A previously obtained refresh token to resume a session with, bypassing the device-code login flow.	None
token_file_path	str	Path to a JSON file used to persist and load the refresh token across runs.	None

login_device_flow()

Start the OAuth2 device-code login flow.

Requests a device code from the Tado API, stores it on self.device_code, self.user_code, self.device_verification_url and self.device_verification_check_interval, and prints the URL the user must visit to log in.

Raises:

Type	Description
Exception	If the device flow has already been started (self.device_activation_status is not NOT_STARTED).

Returns:

Type	Description
DeviceActivationStatus	PENDING, indicating the user still needs to complete login in their browser.

check_device_activation()

Poll the Tado API once to check whether the device-code login has been completed.

Waits self.device_verification_check_interval seconds before polling. On success, stores the resulting access token via set_oauth_token().

Raises:

Type	Description
Exception	If the verification URL has expired before the user completed login.

Returns:

Type	Description
bool	True if login has been completed and an access token was obtained, False if the user has not yet authorized the device (call again to keep polling).

device_activation()

Block until the OAuth2 device-code login flow completes.

Repeatedly calls check_device_activation() until it returns True, then finalizes the session with device_ready().

Raises:

Type	Description
Exception	If login_device_flow() has not been called yet (self.device_activation_status is NOT_STARTED).

device_ready()

Finalize the client after a successful login.

Sets self.id to the ID of the first home returned by get_me(), clears self.user_code and self.device_verification_url, and sets self.device_activation_status to COMPLETED.

refresh_auth(refresh_token=None, force_refresh=False)

Ensure the client holds a valid access token, refreshing it if needed.

Returns immediately without contacting the API if the current access token has not yet expired and force_refresh is False. Otherwise, requests a new access token using refresh_token (or self.refresh_token if not given) and, on success, stores it via set_oauth_token().

Parameters:

Name	Type	Description	Default
refresh_token	str	The refresh token to use. Defaults to self.refresh_token.	None
force_refresh	bool	If True, refresh even if the current access token has not expired yet, and return False instead of raising if the refresh request fails.	False

Returns:

Type	Description
bool	True if the client now holds a valid access token, False if force_refresh was True and the refresh request failed.

save_token()

Persist the current refresh token to token_file_path.

Does nothing if token_file_path or self.refresh_token is not set. Creates the parent directory of token_file_path if it does not exist.

load_token()

Load a previously saved refresh token from token_file_path.

Creates an empty token file at token_file_path if it does not exist yet. Sets self.refresh_token to the value stored in the file, or None if none was saved.

Returns:

Type	Description
bool	True if token_file_path is set, False if no token_file_path was configured.

set_oauth_token(response)

Store an OAuth2 token response and derive the access headers.

Sets self.refresh_token, self.refresh_at and self.access_headers from response, and persists the refresh token via save_token().

Parameters:

Name	Type	Description	Default
response	dict	The parsed JSON body of an OAuth2 token response, containing access_token, expires_in and refresh_token.	required

Returns:

Type	Description
str	The refresh token from response.

get_device_activation_status()

Get the current status of the OAuth2 device-code activation flow.

Returns:

Type	Description
DeviceActivationStatus	NOT_STARTED before login_device_flow() has been called, PENDING while waiting for the user to complete login, or COMPLETED once device_ready() has finished.

get_device_verification_url()

Get the URL the user must visit to complete the device-code login flow.

Returns:

Type	Description
str	The verification URL with the user code appended as a query parameter, or None if login_device_flow() has not been called yet or the device has already been activated.

get_rate_limit_info()

Returns Your account's usage limit and remaining API calls for the Tado API. :return: Object containing how many API calls are allowed to the Tado API, and how many are left in current window.