OAuth2

Authorise Homey to use a Web API with OAuth2.

Introduction

OAuth2 is an authentication standard used often by smart home manufacturers for delegating user access to their Web API. You might have previously encountered this as a "Candy Crush wants access to your Facebook account"-type dialog.

Usually, a developer registers an OAuth2 client on a developer-specific website owned by the manufacturer. Often a Name, Redirect URL, Scopes and/or an Image have to be provided.

Homey's OAuth2 Consent Dialog

Almost always, the Redirect URL has to be entered beforehand for security reasons. Homey is behind a NAT, however, and thus does not have a static URL available to redirect to. For this scenario, you can use ManagerCloud#createOAuth2Callback(). This method generates a unique URL to redirect the user to, which passes the resulting code parameter —which you can then swap for an access token— back to your app.

You can view working examples of Homey Apps that use OAuth2 at: https://github.com/athombv/nl.thermosmart-example, https://github.com/athombv/nl.eneco.toon-example, and https://github.com/athombv/io.nuki-example 

Homey OAuth2App

The recommended way to create a Homey app for an OAuth2 Web API is by using homey-oauth2app.

This module does all the heavy lifting related to OAuth2, such as logging in, obtaining an access token, refreshing tokens and making API calls.

Because no API is the same, the module has been designed specifically to be extended to fit your Web API. Even if your device's Web API differs from the OAuth2 specification, methods can be overloaded to change behaviour.