Authentication

Introduction

Authentication is how you prove that you are who you say you are. In this guide, we will take a deep dive into everything you need to know about authenticating with the SmartBuildings API.

You will need your client_id and client_secret to follow this guide step-by-step. If you don’t have these available, please reach out via 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.

How to authenticate with the SmartBuildings API?

You will need an access token to engage with the SmartBuildings API, which you can generate using the POST /token endpoint with your client_id and client_secret. The audience must always be https://api.sb.ecobee.com, and grant_type must be client_credentials.

Example cURL:

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

API Responses

200 Success

When the client_id and client_secret match our records, the API response will look like this:

{
  "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"
}

Let's take a closer look at this response:

• access_token contains the authentication token. This is a JWT token, which you will send with all subsequent API requests as a Bearer token in the authorization header.
• expires_in tells you how long this access token will remain valid. 7200 means 7,200 seconds, i.e. 2 hours.
• scope contains a list of actions every SmartBuildings user may perform with the API.
• token_type is Bearer. This token serves as proof of authentication and authorization, without you having to use your credentials with every API request.

401 Access Denied

If your client_id and client_secret do not match our records, you will receive this response. Please double check your credentials and try again.

{
  "error": "access_denied",
  "error_description": "Unauthorized"
}

How to make an authenticated API call?

You have successfully generated an access_token for the SmartBuildings API with the POST /token endpoint. Let's use it to make an authenticated API request 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 are following along so far, you will receive a 200 OK status code response with list of buildings in the response body.

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "BUILDING-ID-WILL-BE-HERE",
        "contentLocation": "https://api.sb.ecobee.com/api/v1/buildings/BUILDING-ID-WILL-BE-HERE"
      },
      ...
    ],
    "count": 5
  }
}

However, if your API request did not contain an access_token or if the token was invalid (not formatted correctly or not a generated token), you would receive this response along with a 401 Unauthenticated status code:

{
  "message": "Bad token; invalid JSON"
}

When should I generate a new access token?

Access tokens must be reused until they expire. An access token is valid for 2 hours. However, the exact duration is subject to change. We recommend monitoring the API responses for subsequent requests to detect when your access token has expired. When an access token has expired, but you're still using the same one, the API response will alert you that it is time to refresh your access_token.

{
  "exp": "token expired"
}

At this point, you will make another API call to the /POST token endpoint to generate a new access token, which you must reuse until it expires.

Efficient Access Token Usage: A Step-by-Step example

This is a sample workflow of API requests and responses that follow the SmartBuildings API best practices of handling access tokens.

❌ What not to do?

This hypothetical user is not following the SmartBuildings API best practices. They are generating a new access token for every request. Please only request a new access token when the API confirms that your existing token has expired. Requesting a new access token for each API call may result in your access being suspended.

Recap