msgbartop
Blog di Dino Ciuffetti (Bernardino in realtà)
msgbarbottom

10 Mar 25 TADO ™ unofficial REST API device code flow

If you’re a developer working with Tado’s unofficial REST APIs, you may have recently come across an important update from Tado regarding authentication. In a recent support article, Tado has requested that developers modify their authentication mechanisms to ensure secure and compliant access to their APIs: https://support.tado.com/en/articles/8565472-how-do-i-authenticate-to-access-the-rest-api

This change is critical for maintaining the integrity of Tado’s systems and protecting user data. I’ll break down what this means for developers and how to adapt to the new requirements.

Why the Change?

Tado’s REST APIs have been a popular tool for developers looking to integrate smart home functionality into their applications. However, as with any system, security is an ongoing concern. Tado has identified potential vulnerabilities in the way some developers are handling authentication, particularly when using unofficial APIs. To address these concerns, Tado is now enforcing stricter authentication protocols to prevent unauthorized access and ensure that only legitimate requests are processed.

This move is not uncommon in the tech world. As APIs become more widely used, companies often need to tighten security measures to protect their infrastructure and users. For developers, this means staying up-to-date with these changes and adapting their code accordingly.

What’s Changing?

The primary change revolves around how developers authenticate with Tado’s APIs. Previously, some developers may have relied on less secure methods, such as hardcoding credentials or using outdated authentication flows. Tado is now requiring developers to implement a more robust and secure authentication mechanism.

While the specifics of the new authentication process may vary depending on your implementation, here are some general guidelines to follow:

Use OAuth 2.0: Tado requires using OAuth 2.0 device code flow for authentication, which is a widely adopted standard for secure API access. OAuth 2.0 provides a secure way to handle tokens and ensures that credentials are not exposed in requests.

Avoid Hardcoding Credentials: Hardcoding usernames, passwords, or tokens in your code is a significant security risk. Instead, use environment variables or secure credential storage solutions to manage sensitive information.

Implement Token Refresh: Access tokens typically have a limited lifespan. Make sure your application can handle token expiration by implementing a token refresh mechanism. This ensures uninterrupted access to the API without requiring manual intervention.

How to Update Your Implementation

If you’re currently using Tado’s unofficial APIs, it’s time to review your authentication process and make the necessary changes to implement device code flow. This flow is designed for devices that lack a keyboard or easy input method, such as smart thermostats or mobile apps. Here’s how it works:

  • The device requests a device code and user verification URL from the authorization server

$response = $this->client->post('https://login.tado.com/oauth2/device_authorize',
[ 'form_params' => [ 'client_id' => '1bb50063-6b0c-4d11-bd99-387f4a91cc46,
'scope' => 'offline_access', ], ]);

{"device_code":"ftcrinX_KQaXUNI1wkh-5zxFmmYOUug43SAYWORs1AU","expires_in":300,
"interval":5,"user_code":"9HAZP1",
"verification_uri":"https://login.tado.com/oauth2/device",
"verification_uri_complete":"https://login.tado.com/oauth2/device?user_code=9HAZP1"}

  • The user visits the URL on a secondary device (e.g., a smartphone or computer) and enters the device code, in this case: https://login.tado.com/oauth2/device?user_code=9HAZP1
  • Once the user approves the request with its tado credentials, the device polls the authorization server for an access token
$response = $this->client->post('https://login.tado.com/oauth2/token', ['form_params' => ['client_id' => '1bb50063-6b0c-4d11-bd99-387f4a91cc46',
'grant_type' => 'urn:ietf:params:oauth:grant-type:device_code',
'device_code' => $device_code]]);

[access_token] => eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImd0eSI..............................KcYbYQ
[expires_in] => 599
[refresh_token] => 6Vu1vQadysY-1G6naR8gdp_y-AgFtakb75C7KVK5-uUxgbM3EWHTza2e2D6ZD81W
[refresh_token_id] => 9fa5bb86-8d55-4178-9268-f13bbd1bc1a5
[scope] => offline_access
[token_type] => Bearer
[userId] => 595e1511-078f-8010-332a-0adc13930002

Access tokens have a limited lifespan (10 minutes). Make sure your application can handle token expiration by implementing a token refresh mechanism.

$response = $this->client->post('https://login.tado.com/oauth2/token', ['form_params' => ['client_id' => '1bb50063-6b0c-4d11-bd99-387f4a91cc46','grant_type' => 'refresh_token','refresh_token' => $refresh_token]]);

You can take a look at my working implementation here: https://github.com/dam2k/tadoapi

Enjoy your smart home!

05 Ago 23 dam2k/tadoapi and telegraf-dam2ktado

Ready for a new grafana story? Today I have some more: my brand new opensource repositories:

  • dam2k/tadoapi (packagist and github): a simple Tado ™ SDK implementation for PHP
  • telegraf-dam2ktado (github): API exporter (telegraf execd input plugin) written in PHP

I realized them for myself, after I did not find anything good.

The exporter (telegraf-dam2ktado) is a plugin written in PHP that connects to the tado network (internet), fetches thermostat metrics and devices for your home installation, parses it as a single json and write this json to its stdout. It is signaled directly by telegraf which sends a empty new line on stdout that the plugin catches on its stdin. In this way, the plugin knows when telegraf wants to fetch new data, and telegraf can read parsed and cleaned data from tado so that it can collect metrics and put them to influxdb.

With all the metrics on influxdb one can create a beautiful dashboard on grafana (on cloud or on premise).

The installation instructions are on the respective projects home page.

Now, some cool screenshots of my grafana dashboard (19301)…