Authorization Code Authorization Strategy

This strategy is an implementation of the OAuth 2.0 Authorization Code Grant Type It is ideal for any web based application where the end user is accessing your application through a browser. A series of HTTPs redirects are performed between your web server and the ecobee server which guide the user in authorizing your application in a secure manner.

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

Requesting the Authorization Code

In order to obtain an authorization code, the user's browser must be redirected to the ecobee servers where they will be guided in authorizing your application. To begin the process, redirect the user's browser to the following URL:

GET https://api.ecobee.com/authorize?
		response_type=code&
		client_id=APP_KEY&
		redirect_uri=YOUR_SERVER_URI&
		scope=SCOPE&
		state=YOUR_STATE
				

Request Parameters

Parameter	Description
response_type	This is always "code" 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.
redirect_uri	This is your designated server endpoint for receiving the authorization code and error messages. The URL is limited to 255 characters in total and cannot contain port numbers.
state	OPTIONAL. This is a state string which you can use to uniquely identify this particular request. The state will be returned to you when the authorization code is sent to your server or an error occurs.

Note that the redirect uri you provide cannot contain port numbers as they are not supported.

After the request is made, the user will be directed to log into their ecobee portal and presented with a page which will detail your application and whether the user would like to accept or deny the authorization. The user's browser is then redirected back to the redirect_uri you specified in your original request. The state is also sent back, if included.

Accept Response

The accept response will be forwarded to your designated server endpoint URI.

GET YOUR_SERVER_URI?
		code=AUTHORIZATION_CODE&
		state=YOUR_STATE
				

Decline/Error Response

The decline response will be redirected to your designated server endpoint URI.

GET YOUR_SERVER_URI?
		error=access_denied&
		error_description=ERROR_DESCRIPTION&
		state=YOUR_STATE
				

Now that you have the authorization code, you may use it to obtain access and refresh tokens from the server.

The authorization code has a life time of 10 minutes. Once received, your server should immediately use the authorization code to obtain access and refresh tokens. The tokens should be stored securely.

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=authorization_code&
		code=AUTHORIZATION_TOKEN&
		redirect_uri=YOUR_SERVER_URI&
		client_id=APP_KEY&
		ecobee_type=jwt
				

Request Parameters

Parameter	Description
grant_type	This is always "authorization_code" for this authorization flow.
code	The authorization code obtained from the /authorize request.
redirect_uri	This is your designated server endpoint which was sent in the original authorization code request. They MUST be identical.
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 look 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 the "Access Token" section in Getting Started with Request and Response for information on setting the Authorization header.

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

Error Handing

The following errors should be expected by your endpoint:

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

Since HTTP error codes cannot be set on an HTTP client redirect, they will not be sent.

See Authorization Errors for complete descriptions and list.

Back To Top