PIN Authorization Strategy

The ecobee PIN authorization method is designed to support any 3rd party device, be it a mobile phone, tablet, desktop widget or remote server. This authorization method allows a 3rd party application to obtain an authorization code and a 4 byte alphabetic string which can be displayed to the user. The user then logs into the ecobee Portal and registers the application using the PIN provided. Once this step is completed, the 3rd party application is able to request the access and refresh tokens.

On December 1, 2020, there will be changes to the API that affect token format and authorization flows, including PIN Authorization. See here for more information.

Requesting the PIN

The first step is for the application to request an authorization code and a PIN. The PIN will be displayed to the user as well as the amount of time the user has before the PIN expires. The expiry duration is returned along with the PIN.

Authorize Request

GET https://api.ecobee.com/authorize?
		response_type=ecobeePin&
		client_id=APP_KEY&
		scope=SCOPE
				

Request Parameters

Parameter	Description
response_type	This is always "ecobeePin" for this authorization flow.
client_id	This is the unique application key for your application.
scope	This is the Scope the application requests from the user.

Authorize Response

If successful, the response will be:

{
   "ecobeePin": "bv29",
   "code": "uiNQok9Uhy5iScG4gncCAilcFUMK0zWT",
   "scope": "smartWrite",
   "expires_in": 9,
   "interval": 30
 }

Response Properties

Property	Description
ecobeePin	The PIN a user enters in the web portal.
expires_in	The number of minutes until the PIN expires. Ensure you inform the user how much time they have.
code	The authorization token needed to request the access and refresh tokens.
scope	The requested Scope from the original request. This must match the original request.
interval	The minimum amount of seconds which must pass between polling attempts for a token.

At this point, the application should display the PIN to the user and request that they log into their web portal and register the application using the PIN in their My Apps widget.

User Authorizations via Portal

The user will go to the portal, and, within 10 minutes, enter the PIN in the My Apps widget to add the app. Meanwhile the application will periodically poll the server. Alternatively, the application can request the user click a button on the application when they are done. The choice is up to the individual developer.

Requesting Tokens (Access & Refresh)

The application will need to request access and refresh tokens once the user has authorized the application within the ecobee Web Portal.

POST https://api.ecobee.com/token?
		grant_type=ecobeePin&
		code=AUTHORIZATION_TOKEN&
		client_id=APP_KEY&
		ecobee_type=jwt
				

Request Parameters

Parameter	Description
grant_type	This is always "ecobeePin" for this authorization flow.
code	The authorization code obtained from the /authorize request.
client_id	This is your unique application key.
ecobee_type	Optional. Specify "jwt" to have the API return access tokens as JWTs. If not specified, the API will return opaque access tokens.

A successful response will like like this:

{
	"access_token": "Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg",
	"token_type": "Bearer",
	"expires_in": 3599,
	"refresh_token": "og2Obost3ucRo1ofo0EDoslGltmFMe2g",
	"scope": "smartWrite" 
}				

If ecobee_type=jwt was specified, then the response will look like this:

{
	"access_token": "eyj.....5ef9",
	"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.

At this point, the application should store the access and refresh tokens in its secure local store. These tokens represent the credentials of the user and must be kept secure.

The token_type returned must be specified in the Authorization header when making API requests. See Getting Started with API Requests for information on setting the Authorize header.

After you have the tokens, you may now begin making API requests using the access token.

Error Handling

A number of errors may be returned which must be handled by the caller in an appropriate fashion.

• authorization_pending (HTTP 401)
• authorization_expired (HTTP 401)
• slow_down (HTTP 401)

See Authorization Errors for complete descriptions and list.

Back To Top