Core Concepts of Authorization
On December 1, 2020, there will be changes to the API that affect token format and authorization flows. See here for more information.
The ecobee API is based on extensions to the OAuth 2.0 framework. OAuth 2.0 is an emerging industry standard authorization framework which provides a good base for a common framework. Today it is used by some of the largest and most popular internet sites. The 2.0 specification is still evolving, and improves upon the original specification, however it does not address adequately device authentication. As a result, many sites have implemented custom extensions which utilize the framework provided extension mechanisms. The ecobee API uses such extensions in order to minimize the effort and complexity for developers yet still provide a deep level of security for end users.
Knowledge of the OAuth 2.0 framework is not required to make use of this API. All required and relevant information regarding the use of the ecobee API is provided within this documentation. However it may be helpful to the developer to be aware of the intent and workings of the OAuth framework.
Authorization
By definition, authorization is the act of specifying access rights to resources. In this case, it is the act of obtaining rights to read and/or update thermostats. The ecobee API permits a developer to request authorization for access to the thermostats registered to a user's account. The extent of the access rights granted is expressed in terms of scope.
The ecobee API supports three methods of authorization:
Authorization Code
Authorization Code is a web browser based authorization method which is intended for 3rd party web sites and web applications. This method utilizes a series of web redirects to guide the user in the authorization between your web site and ecobee's.
PIN Authorization
Third party authorization for any device is always done using the PIN Authorization method. This simplifies the process of authorization for the developer and end user and will work for any type of 3rd party application.
Utility Authorization
Special accounts such as Utilities are permitted an alternate method of authorization using implicit authorization. This method permits the Utility application to authorize against their own specific account without the requirement of a PIN. This method is limited to special contractual obligations and is not available for 3rd party applications who are not Utilities.
Scope
The ecobee API scope defines exactly what the API is capable of accessing for a given user's account. The scope explicitly details the intent of the API application towards the user's account. This permits a user to decide whether they wish to approve this access, or not. For example, the scope may be limited to viewing and not updating of thermostats, or it may be more broad such as read and update thermostats.
It is important to note that EMS accounts support multiple users and a fine grained permission system. Whatever the scope of the application, users will always be limited to the privileges they are granted to the set hierarchy in the EMS Web Portal.
Supported Scopes
| Scope | Account Types | Description |
|---|---|---|
| smartRead | Smart Only | Permits read-only access to user registered Smart thermostats. |
| smartWrite | Smart Only | Permits read-write access to user registered Smart thermostats. |
| ems | EMS Only | Permits read-write access to EMS thermostats, honours EMS set hierarchy privileges. |
There is no scope provided to Utilities. Utility accounts utilise the implicit authorization method.
You may request multiple scopes by providing them in a CSV format i.e. "smartWrite,ems" to request permission to Smart and EMS thermostats.
See account types under Core Concepts.
ecobee reserves the right to make the scope permissions to be more granular in the future should the need arise.
Tokens
The ecobee API utilizes a token-based authorization and authentication strategy. This provides the maximum level of security and eliminates the need for a 3rd party application to request user credentials and store them. Rather, tokens are issued, stored and utilized by the 3rd party application. All tokens have a limited life span and expire. Expiry is determined by the type of token issued. These expiry periods are documented under Token Refresh and under each authorization strategy as needed.
All tokens are 32 byte alphanumeric strings.
Treat all tokens as you would a username and password. The access token should be kept secret and secured at all times.
Application Key
The application key is a 32 byte alphanumeric identifier which uniquely identifies a 3rd party application. Each application has its own application key which must be used during the authorization process. An application key is created for you when you create a new application in your Developer Portal. Application keys are permanent and never expire. The application key is your secret which permits calls to be made to ecobee on behalf of your application.
You are ultimately responsible for your application key. It should never, under any circumstances be shared or given away. Should ecobee detect that an application key has been compromised, it will be revoked. Once this occurs all deployments of your application will stop working.
Authorization Token
The ecobee API utilizes unique tokens for authorization and access. When requesting authorization, an authorization token will be issued which will be used in subsequent authorization requests. The authorization token identifies the current chain of authorization requests and is later exchanged for access and refresh tokens.
Access Token
Access tokens encapsulate the authorization scope and credentials. These tokens replace the need to know or utilize the credentials of a user. The intent is that a 3rd party application never asks nor stores the user's credentials, rather it stores the access token which is then used to make API calls. Access tokens have a limited lifetime and must be refreshed periodically.
Refresh Token
Unless specified elsewhere, all access tokens are also issued with a corresponding refresh token. The refresh token must be stored by the 3rd party application and used when an expired token response is returned by the server. A refresh of the tokens will result in a new access token. The same refresh token can be re-used to obtain new access tokens. See Token Refresh on how to refresh tokens.
Refresh tokens, once issued, expire after some time, as outlined in the token refresh documentation. Typically this is a year. After it expires, your application will require to be re-authorized. Until the token expires, you are free to re-use it to refresh access tokens for the user.
User Authorization Management
The ecobee Portal users are able to view and manage the 3rd party application which they have granted access to their account. At any time the user may revoke the application access to their account. This is all managed through the My Apps widget in the ecobee Portal.