Remote API

The Hue bridge can be accessed locally or remotely. The same API calls are valid for both (mostly) and this library can operate both against local and remote versions of the Hue Bridge API.

Prerequisites

There are some prerequisites that must be met before you can attempt to utilize the Remote version of the Hue Bridge API.

• Developer Account on the https://developers.meethue.com portal
• Remote Hue API Application registered for your application

Registering a Developer Account

You can register for a developers account by filling in the details on the registration page, https://developers.meethue.com/register/.

Once you have this account, you can sign in to the https://developer.meethue.com portal and then register your remote application with them.

Creating a Remote Hue API Application

Once you have signed into the https://developers.meethue.com portal using you developers account, you can register a Hue API Remote Application by selecting your username in the masthead and then clicking on the Remote Hue API appids link.

This will display your existing remote applications that you have registered as well as giving you a link to create a new application.

When you click a new application, you are required to fill a number of details about your application which consist of:

• App name: An Application name for your application, this will be what is presented to users when they authorize your application via the Remote API initial token generation
• Callback URL: A URL that will be used in the callback when generating the necessary code for getting the Remote API OAuth tokens. This is really expected to be a URL that is valid
• Application Description: A description of the application
• Company Details: These appear to be optional at this time

You will need to read and accept the terms and conditions for the API. It is up to you to adhere to these the library will not do anything specific to ensure you are complaint with these terms and conditions.

Callback URL

The Callback URL is going to be redirected to from an initial authentication grant by the user when granting access to the Hue Remote API by a user.

This process flow ideally needs to occur in the browser and for cloud/internet hosted applications, it will not be difficult to have an endpoint exposed that will collect the information from this callback redirect and make it available to your application. It is an OAuth flow after all.

If you are not hosting your application exposed to the internet, then you can still obtain the code that you need to exchange for tokens by registering any URL for the Callback URL, say http://localhost:8080, then the browser will still redirect to that URL along with the query parameters containing the code and state. You can then extract those values from the URL in the browser after it fails.

Alternatively you can run a simple server on the localhost or internal network address that can be used for the Callback URL (currently the callback URL does support the use of localhost, but this may change in the future). You can then run something as simple as the following code to capture the values from the Callback URL:

// Using Hapi as the server, could use express as well...
const Hapi = require('@hapi/hapi');

const init = async () => {
  const server = Hapi.server({
    port: 9090,
    host: 'localhost',
  });

  server.route({
    method: 'GET',
    path: '/',
    handler: (request) => {
      const code = request.query.code
        , state = request.query.state 
        ;
      return {
        code: code,
        state: state
      }
    }
  })

  await server.start();
  console.log('Server running on %s', server.info.uri);
}

process.on('unhandledRejection', (err) => {
  console.log(err);
  process.exit(1);
});

init();

Connecting with the Remote API

Once you have set up the Remote API Application with the https://developers.meethue.com portal, you can then use the application data along with the library to generate your OAuth tokens needed for remote access.

Navigate to your Remote Hue API Application and collect the ClientId and ClientSecret along with the AppId for the remote application, these are needed so that we can talk with the Hue Remote API endpoints.

There are two possible paths that you have for accessing the Hue Remote API;

• New Connection to the Remote Hue API Application
• Reusing an existing Access Token to connect to the Remote Hue API

New Remote Application Connection

In this scenario you have never generated (or lost your previous) OAuth Access Token to the Remote Hue API. The flow that the Hue Remote API requires in this case is:

1. An access URL is generated that the user can issue an HTTP GET on (this includes a state) code which you can use to detect forgeries from your application code.
2. User navigates to the provided URL, which will redirect them to sign in to the https://account.meethue.com website
3. After the user is signed in, they will prompted with a Grant permission page that will show the name of your application (the AppId), that they must accept to grant you access to their account and bridges.
4. Once the user accepts the grant request, they will be redirected to the Callback URL of the Hue Remote Application that you set up above. There will be two query parameters in the callback URL that the user is redirected to, code and state.
5. The code and state parameters that are received in the callback need to be collected. The state is the same state value that was passed in via the initial access URL, you can validate this to ensure that the response is associated with the one you sent. The code is the value you need to exchange with the Remote Hue API to obtain your OAuth Access Token.
6. Call the connectWithCode(code, username) function to exchange your code for OAuth Access and Refresh Tokens
7. Interact with the remote bridge (after you have stored the tokens for future use) using this library API.

Reusing Existing OAuth Tokens

In this scenario, you have already gone through the New Remote Application Connection process and stored the Access Token and Refresh Token so that you can reuse them.

1. Instantiate a remote api via the library
2. Call connectWithTokens() function to attach to the Hue Remote API using the provided tokens
3. Interact with the remote bridge using this library API

Note: You are responsible for passing a valid unexpired access and/or refresh token. The tokens will expire after a period of time, the times of which are availble via the API when they are first obtained.

Remote Users / Whitelist

The remote API is fairly useless unless you have a remote user created. The library will create a new user for you in the Hue Remote API whitelist if you do not pass in an existing username. Note, this is different to the approach that is taken with the local API connections of this library.

When you call either connectWithCode() or connectWithTokens() and do not provide a username parameter a new remote user will be created as part of the connection to the remote API. The reason for doing this is to make the remote API more usable as unlike the local API, where you now need to press the link button on the bridge, this can be automated via the Hue Remote API.

If you are not passing an existing username when connecting, you can collect the username that was created at connection time using the api.remote.getRemoteAccessCredentials() function.