Example 1: Authenticating your app

The API uses the OAuth standard for authentication. We will demonstrate the PIN based method. The sequence of calls is depicted in the diagram below:

Let's get started with the first request to obtain our ecobeePin. Note that you will need your API Key, which can obtained when you create your app in the ecobee portal through the developer panel.

To access the developer panel, click on the 'Developer' tab located in ecobee's right-hand-side portal menu. Then create a new app by clicking 'Create New', select 'ecobee PIN' as the Authorization Method and click Save. Make note of the API Key. The process for this is illustrated below.

For the next few steps, we have created a series of JavaScript forms that perform real calls to the ecobee API. Responses for each call can be observed as well as the actual JavaScript used to make the call.

Step 1: Obtaining your Pin and Authorization Code

Paste the application's API key below and press 'Submit'.

Response JSON:

If all goes well, you should receive a response below that contains an ecobeePin and code along with a few other fields.

(Step 1 response JSON will appear here)

The JavaScript below was used to carry out this request:

							
var apiKey = $('#apiKey').val();	
var url = "https://api.ecobee.com/authorize?response_type=ecobeePin&client_id=".concat(apiKey).concat("&scope=smartWrite");	
$.getJSON(url,  function(data) {
	var response = JSON.stringify(data, null, 4);
 	$('#authorizeResponse').html(response);
});                			
                			

Copy your ecobeePin as seen in the response above. At this point, goto ecobee.com, login to the web portal and click on the 'My Apps' tab. This will bring you to a page where you can add an application by authorizing your ecobeePin. To do this, paste your ecobeePin and click 'Validate'. The next screen will display any permissions the app requires and will ask you to click 'Authorize' to add the application. The process for this is illustrated below.

For your convenience, the code (the Authorization Code) from the previous response along with your API Key has been pre-populated in the next request form below.

Now that you have authorized your app using your ecobeePin, the next step is to obtain your access_token.

Step 2: Obtaining your Access Token and Refresh Token

Ensure that both the API Key and Authorization Code fields are populated and press 'Submit' to perform an API call to obtain an Access Token. This token will be needed for all future API calls.

Response JSON:

If all goes well, the response below should contain the required tokens needed to make further API requests.

(Step 2 response JSON will appear here)

The JavaScript below was used to carry out this request:

apiKey = $('#apiKey').val();
authCode = $('#authCode').val();

var url = "https://api.ecobee.com/token"
var data = "grant_type=ecobeePin&code=".concat(authCode).concat("&client_id=").concat(apiKey);

$.post(url, data, function(resp) {
	var response = JSON.stringify(resp, null, 4);
	$('#tokenResponse').html(response);
}, 'json');	
                			

Your app must remember the access_token and refresh_token values. The access_token is used to make API requests, and the refresh_token is used to obtain another valid access_token once the current access_token expires. An access_token expires in 60 minutes, while a refresh_token takes one year to expire.

Let us take a look at how to perform a token refresh.

Step 3: Performing a Refresh Token

Like in Step 2, the API Key has been pre-populated for your convenience. This time, copy the refresh_token returned in the response of Step 2 into the 'Refresh Token' field. Press 'Submit' to obtain a new set of tokens.

Response JSON:

If all goes well, you will receive a new access_token and refresh_token in the response below.

(Step 3 response JSON will appear here)

The JavaScript below was used to carry out this request:

		
apiKey = $('#apiKey').val();
refreshToken = $('#refreshToken').val();
   
var url = "https://api.ecobee.com/token";
var data = "grant_type=refresh_token&code=".concat(refreshToken).concat("&client_id=").concat(apiKey);
  	
$.post(url, data, function(resp) {
	var response = JSON.stringify(resp, null, 4);
  	$('#refreshTokenResponse').html(response);
}, 'json');										
							

Every time you refresh your token, your app must remember the new pair of access and refresh tokens from the result.

Recommendation: When you start a new working session with your user, it is a good idea to refresh your access_token, since there may be a high likelihood that your previous access_token may have expired.

Now let us get some thermostat details with our next example.