OAuth2/Authorization Guide
If you've never used OAuth2.0 before for an API (or even if you have) we know that it can be pretty intimidating and tough to figure out at first. Especially when it comes to the Authorization Code flow. Hopefully we can help demystify some of what's going on and get you started using the API outside of the documentation!
The Authorization Request
First you make a call to the OAuth2 Authorize endpoint in a browser with your API Key and your Redirect URI (explained later). This tells us who you are and ensures you have valid access to our API. The API call is structured like this:
https://api.honeywellhome.com/oauth2/authorize?response_type=code&client_id={apikey}&redirect_uri={redirectUri}
You can also include an optional &state= parameter that will be returned when we send you the Authorization Code. This can be used for both security and tracking purposes
What happens now is we redirect the user through the browser to a login page where they enter their Lyric Username and Password (same as they would use in the app).
Assuming a valid username and password are entered, we then present a consent screen to the user detailing the data we will share with your application and the functionality allowed
The Authorization Code
Once all of the above is complete, the API will then redirect the request to your previously defined Redirect URI with a &code=codezxc890 parameter that has a short alphanumeric code with it. We also include the &state= parameter if you specified it earlier. If you did include that to start with, verify it's the same to ensure security is intact.
Now we want to take that Authorization Code and make a POST request to the /oauth2/token endpoint combined with your API Key (consumer key) and API Secret (consumer secret).
The Authorization HTTP header for this request is a Base64 encoded value of apikey and apiSecret concatenated with a colon. For example if your API Key was 123abc and your Secret was 456def your HTTP header would look like this:
Authorization: Basic MTIzYWJjOjQ1NmRlZg==
A full example curl request would look something like this:
curl -X POST 'https://api.honeywellhome.com/oauth2/token' -H "Authorization: Basic MTIzYWJjOjQ1NmRlZg==" -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=authorization_code&code=zxc890&redirect_uri=<redirectUriHere>'
The result!
As long as everything else went OK you will receive a response that looks like this:
{
"access_token": "k8sbPR4is2C7ipTYgEbi8fe470mp",
"refresh_token": "dQJiREMfaHhDBoGohIj7JEpIOYYk9Jif",
"expires_in": "599"
}