Getting Started

You will need an active SmartBuildings subscription, a client ID and a client secret in order to use the SmartBuildings API. If you don’t have these available, please send an email to [email protected].

Please note that these API credentials are different from the username and password you use to login to the SmartBuildings portal.

Authentication

Authentication is how you prove that you are who you say you are. On the SmartBuildings API, you do this by making an API call to the POST /token endpoint, with your client_id and client_secret.

curl --request POST \
  --header "Content-type: application/json" \
  --url "https://api.sb.ecobee.com/token" \
  --data '{ "audience": "https://api.sb.ecobee.com", "grant_type": "client_credentials", "scopes": "read:thermostat read:thermostats", "client_id": "YOUR-CLIENT-ID-HERE", "client_secret": "YOUR-CLIENT-SECRET-HERE" }'

If your client credentials are valid, the API will return a Bearer access_token and an expires_in timestamp indicating when the access token will expire. An access_token is valid for 2 hours, but we recommend checking the expires_in value as this may change in future releases.

{
  "access_token": "YOUR-ACCESS-TOKEN-HERE",
  "scope": "create:building create:thermostat delete:building delete:thermostat read:building read:buildings read:thermostat read:thermostats write:building write:tenantmode write:thermostat",
  "expires_in": 7200,
  "token_type": "Bearer"
}

This access_token should be reused for all subsequent interactions with the SmartBuildings API until expiration. You will know when to refresh your access token when the API responds to your requests with a 401 Unauthorized status code and { "exp": "token expired" } in the response body.

Please take care to only request a new access token when the API confirms that your existing token has expired. Please do not request a new access token for each API call.

List of Thermostat IDs

As a quick test, let’s take our newly generated access token and make an API call to the GET /buildingIds endpoint to get a list of thermostat IDs in your SmartBuildings account.

curl --request GET \
  --header "Authorization: Bearer YOUR-ACCESS-TOKEN-HERE" \
  --url "https://api.sb.ecobee.com/api/v1/thermostatIds"

If you get a successful response with status code 200, you've made your first authenticated API call to the SmartBuildings API.

Next Steps

Congratulations, you made it. You have successfully generated an access_token for the SmartBuildings API, checked when the token expires with expires_in, and listed the thermostats in your SmartBuildings account.

Please refer to the following sections to learn more about how you can build a high quality and reliable system that integrates with the SmartBuildings API: