Skip to content

/ node-hue-api

Permalink
master

node-hue-api/docs/remoteApi.md

Go to file
Adding Support for the Hue Remote API
Latest commit 483fe9a Sep 6, 2019 History 
- Changes to the underlying APIs to support both local and remote access
- Adding new Hue Remote API endpoints and OAuth Authentication, issue #125
- Documentation for using Hue Remote API witht he library
- Modified Error handling due to changes over Axios due to differences
in the local and remote APIs
- Fixing Debug output in the library
- Disabling tests that cannot operate cleanly
1 contributor

Users who have contributed to this file

43 lines (28 sloc) 2.17 KB
Raw Blame

Remote Hue API Support

There is a remote access version of the Hue API that is available to users that have registered their bridges with the Philips Hue Portal.

From a software perspective and this library, it does support the Remote Hue API, but this requires a number of things to be in place for you to be able to authenticate with the Remote Hue API.

This library does most of the heavy lifting for you with respect to handling the various challenges that are necessary for setting up the remote OAuth tokens and users.

That said it is still beneficial to understand the overall authentication flow which is detailed at: https://developers.meethue.com/develop/hue-api/remote-authentication/

The steps in configuring and getting up and running with the remote API are detailed in the steps below:

  1. Setup
  2. Remote Bootstrap
  3. Use the api from the connectXXX() call to interact with the bridge as you would locally.

OAuth Tokens Security and Expiry

Once you have successfully established a connection via the Hue Remote API, there will be two OAuth tokens (for access and refresh) that you need to keep hold of for future (re)connections.

It is up to you as a developer/user of the library to store these securely where ever you deem appropriate, considering that these tokens provide complete remote access to your Hue Bridge via the internet!

These token also have a limited window of validity, so if they are compromised at least they will expire out, eventually...

Due to the tokens having an expiry, it is up to you to ensure you renew them using the api.remote.refreshTokens() function call, whilst the refresh token is still valid.

If you let the tokens expire then you will need to perform the re-authorization against the Hue Remote API utilizing the Callback URL of your Hue Remote API Application and granting access, then exchanging that authorization code for the new tokens.

Examples

There are working examples of establishing remote access:
You can’t perform that action at this time.