SmartApp Connector

A cloud-connected device communicates to SmartThings Cloud through a third-party cloud and a Cloud Connector.

A SmartApp Connector is typically used for implementing certain advanced features or customizing your device onboarding UX.

Cloud-connected device

This article demonstrates how to create a cloud-connected light bulb. We provide a WebHook SmartApp that serves as the Connector. The sample code uses the SmartThings API to import LIFX bulbs into your SmartThings account.

In this tutorial, we will cover:

  • SmartApp installation and configuration flow.
  • HTTP Signature verification to ensure that the incoming requests are from SmartThings.
  • Integrating with a third-party API (LIFX API, in this case).


  • Node.js and npm installed (verified with npm version 4.0.5 and Node 7.4.0).
  • ngrok installed to create a secure tunnel for a globally available URL for fast testing.
  • Docker for running Redis. Alternatively, install and run Redismanually.
  • A Samsung account and the SmartThings app (currently available for Android).
  • At least one LIFX light bulb and the LIFX Mobile app (to install the light).
  • Either a LIFX Client ID and Client Secret (obtained from LIFX) or a LIFX personal API Token(generated during Connector installation).

Step 1: Set up the Connector

Use our sample Cloud Connector to enable communication between LIFX and SmartThings Cloud.

  1. Download the SmartThings LIFX Connector on GitHub, using steps 1-7 in the README to set up the sample.
  2. Set your OAuth configuration.
  3. Run WebHook Service.

Step 2: Create a device profile

You must create a device profile for the SmartApp Connector.

  • Enter My Bulb as the Device Profile Name.
  • For the Device Type, select Light.
  • Inside the main component, add the following capabilities:
    • Color Control
    • Color Temperature
    • Switch
    • Switch Level
  • For both Dashboard State and Dashboard Action, select main as a component and select Switch as a capability.

Step 3: Register Connector in Developer Workspace

You should now have all the information required to register your Connector in Developer Workspace.

Select SmartApp Connector and select the Webhook Endpoint hosting type.

  • Select My Bulb (created above](#Step-2-create-a-device-profile)) as the device profile.
  • Select WebHook endpoint.
  • Select the following OAuth2 scopes:
    • r:devices:*
    • w:devices:*
    • i:deviceprofiles
  • Enter a Connector Display Name to be shown in the SmartThings app.
  • Set SmartApp Instances to Single.

After saving your Connector info, return to the Cloud Connector page to find the following information:

SmartApp Connector info

  • Copy the Public Key and replace the contents of the file config/ with it.
  • Copy the Client ID and Client Secret values into the corresponding entries in config/default.json under "Connector".

Find the Device Profile ID on the Device Profile page.

  • Copy and paste the device profile ID field into config/default.json in the "deviceProfiles": {"color": ""} entry.

Step 4: Restart your WebHook service

  1. Stop the npm server: CTRL-C.
  2. Start the server again: npm start (this ensures that the Public Key will be used to verify requests from SmartThings).

Test your device

Start testing your device with the SmartThings app.

After adding your device in the app, you will see the light bulb. Tap on it to install it.

Check your OAuth configuration:

  • If you have configured your server for OAuth with a Client ID and Client Secret from LIFX, you will be prompted to connect to the LIFX site to import your devices into SmartThings. In this case, the LIFX access token is stored for use by your app via the standard OAuth process.
  • If your server isn't configured for OAuth (i.e. no Client ID and Client Secret) then you will be prompted to manually enter a personal access token. Generate a new token (Step 3 of setting up the SmartThings LIFX Connector) and paste the token into the "Enter your LIFX API token" field.


  • When installing the SmartApp, if you get the error Something went wrong. Please try to install the SmartApp again, then:
    • Make sure you restart the npm server as specified above above. If you did not restart the npm server, you will see this error in the npm server terminal: forbidden - failed verifySignature.

See also