Refreshing Your Tokens
All access tokens must be refreshed periodically. Token refresh reduces the potential and benefit of token theft. Since all tokens expire, stolen tokens may only be used for a limited time. A token refresh immediately expires the previously issued access token and issues a brand new token. Refresh tokens can be reused to obtain new access tokens.
On December 1, 2020, there will be changes to the API that affect token format and authorization flows. See here for more information.
Refresh Token Request
To refresh your token, make the following request:
POST https://api.ecobee.com/token?
grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=APP_KEY&
ecobee_type=jwt
The ecobee_type parameter (optional) specifies the return format of the token. Specifying 'jwt' will result in tokens returning in JWT format. Not including this parameter will result in opaque tokens being returned.
After December 1, 2020, all access tokens returned will be JWTs, regardless of whether or not the ecobee_type param is specified. Please see here for more information.
The code parameter is also supported for the refresh token value.
POST https://api.ecobee.com/token?
grant_type=refresh_token&
code=REFRESH_TOKEN&
client_id=APP_KEY&
ecobee_type=jwt
Where REFRESH_TOKEN is the refresh token you were issued and the APP_KEY is the application key for your application.
The response, if successful will contain:
{
"access_token": "Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "og2Obost3ucRo1ofo0EDoslGltmFMe2g",
"scope": "smartWrite"
}
If ecobee_type=jwt is specified, then the response will look like this:
{
"access_token": "eyj.........53ef9",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "v1.X8NZrkUNOmTAds9Jypj5T_HwtSkalKKaaKKXaGzv5CcLe",
"scope": "smartWrite"
}
After December 1, 2020, all access tokens returned will be JWTs, regardless of whether or not the ecobee_type param is specified. The format for refresh tokens will also be changing. Please see here for more information.
On error, see API Requests and Responses for information on handling errors.
Token Expiry
The following table lists the expiry for common token types. Additional information may be found under each authorization strategy.
| Token Type | Expiry |
|---|---|
| Authorization | Variable: see strategy documentation |
| Access | 3600 seconds (1 hour) |
| Refresh | 1 year (14 days if it is the first refresh token returned immediately after authorization) |
After December 1, 2020, expiry times for tokens will be updated to the following:
| Token Type | Expiry |
|---|---|
| Authorization | Variable: see strategy documentation |
| Access | 3600 seconds (1 hour) |
| Refresh | 30 days |
What happens if I lose my Access/Refresh tokens or they expire?
Should you lose your access and refresh tokens, or they expire you will need to begin the authorization process from the beginning. Your application must be capable of handling this use case.