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!