Developer App Migration Strategy

We’ve been working on updating our authentication system to add support for 2FA, and in the process have changed a number of things related to our various authorization strategies and mechanisms. These changes will be enforced starting on December 1, 2020. To ensure that our users do not experience an interruption in services from our developers, this document will list all of the changes that will be made, as well as steps to migrate effortlessly into the new world.

General Changes to Access / Refresh Tokens

Access Tokens

Access tokens will now always be returned as JWTs, which are longer than our legacy 32 character format, and use a much wider character set. Note that token and PIN changes affect /token and /authorize requests, as well as the Authorization: Bearer header for all other requests.

To ensure that your application will continue to work after December 1, 2020, the following steps will need to be taken:

  • Update your application so it can handle tokens up to 7KB in length which can include upper and lower case alphanumeric characters, hyphens, underscores, and periods (we use JSON Web Signature tokens following RFC7515).

Refresh Tokens

Refresh tokens will now be of varying lengths and can contain non-alphanumeric characters. Refresh tokens will also never expire (they used to have an expiry of 1 year). It is important that refresh tokens are treated like secrets and are kept safe and secure.

To ensure that your application will continue to work after December 1, 2020, the following steps will need to be taken:

  • Update your application so it can handle the new format of refresh tokens.

Users with existing refresh tokens will continue to use the legacy authentication service. As the new service is designed for increased availability and reliability, we recommend all users re-authorization their applications to obtain new refresh tokens from the new system.

Authentication Code Flow Changes

Redirect URIs registered with ecobee for your application are now required to match the redirect_uri parameter used in calls to the /authorize endpoint. Redirect URIs must start with https:// protocol, cannot include port numbers, and are absolute URIS, such as:

					https://myapplication.com/oauth/callback
Rather than what we required for our legacy domains, which was simply a domain such as: 
					myapplication.com

To ensure that your application will continue to work after December 1, 2020, the following steps will need to be taken:

  • Update the Redirect URI registered with your application to be a comma-separated list of absolute URLs that start with https://, and do not contain port numbers. For backwards compatibility during the migration, the hostname of the first provided URL will be used for authorization requests that do not specify the ecobee_type=jwt parameter

ecobeePin Flow Changes

PINs, which were previously 4 character alphanumeric strings, will now be at least 8 characters and may include hyphens or spaces.

Users will also see a brand new consent screen when they enter their PIN code in consumer portal, which users will have to agree to in order to continue.

To ensure that your application will continue to work after December 1, 2020, the following steps will need to be taken:

  • Update your application so it can handle/display the longer pin code to users.
  • Update any documentation the application has so users will not be surprised when they see the new consent screen.

ecobee only recommends the PIN strategy for use cases where the user is interacting with a device that cannot easily use a web-based login form. During the migration process, you may choose to migrate to the Authentication Code Flow for a better user experience.

To migrate your application from using ecobeePin to authentication codes:

  1. Ensure your application can handle the changes to our tokens as described above without truncation.
  2. Add ecobee_type=jwt to https://api.ecobee.com/authorize?response_type=code requests, so they will be https://api.ecobee.com/authorize?response_type=code&ecobee_type=jwt...
  3. Edit your application in the developer console (see here for more info on accessing the developer console):
    • Update the authentication strategy to be code
    • Provide all the redirect URIs that your application uses for the authorization code flow. These need to be absolute URLs and cannot include fragments after a hash (#) character. Note that our legacy setup requires only a domain, and our new strategy requires an exact URL; you can specify multiple if you provide them as a comma-delimited list.

Back To Top