Simple API Access App Example

Overview

This simple NodeJS Express app illustrates how to create an API Access SmartApp that connects to your SmartThings account with OAuth2 and allows you to execute scenes. It's a very simple app that stores the access and refresh tokens in session state. By default it uses the express-session in-memory session store, so you will lose your session data when you restart the server, but you can use another compatible session store to make the session persist between server restarts. This example uses the @SmartThings/SmartApp SDK NPM module for making the API calls to list and execute scenes.

Files and directories

public
- stylesheets -- stylesheets used by the web pages
views
- error.ejs -- error page
- index.ejs -- initial page with link to connect to SmartThings
- scenes.ejs -- page that displays scenes and allows them to be executed
server.js -- the Express server and SmartApp
.env -- file you create with app client ID and client secret

Getting Started

Prerequisites

A Samsung Developer Workspace account with API Access app approval. Submit requests for approval using this form
Node.js and npm installed
ngrok or similar tool to create a secure tunnel to a publically available URL (This is required because the Developer Workspace does not allow HTTP or localhost in callback URLs. As an alternative, you can edit your local machine's hosts file so that your app can have a redirect URL that isn't localhost).

Instructions

Clone this GitHub repository, cd into the directory, and install the Node modules with NPM:

git clone https://github.com/SmartThingsCommunity/api-app-minimal-example-js.git
cd api-app-minimal-example-js
npm install

Create a file named .env in the project directory and set the base URL of the server to your ngrok URL (or the URL you configured in your local hosts file):

SERVER_URL=https://your-subdomain-name.ngrok.io

Start your server and make note of the :

node server.js

Website URL -- Use this URL to log into SmartThings and connect this app to your account:
https://your-subdomain-name.ngrok.io

Redirect URI -- Copy this value into the "Redirection URI(s)" field in the Developer Workspace:
https://your-subdomain-name.ngrok.io/oauth/callback

Go to the SmartThings Developer Workspace and create an new API Access project in your organization. If the previous link doesn't work and you don't see an option for creating an API access project, then your access has not yet been approved.
After creating the project click the Use the Register an Application link and fill in the fields, and click Save. Use the Redirect URI value printed out in the server log and specify the r:locations:*, r:scenes:*, and x:scenes:* scopes.
Add the CLIENT_ID and CLIENT_SECRET properties from the Developer Workspace to your .env file. For example:

SERVER_URL=https://your-subdomain-name.ngrok.io
CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx

Restart your server:

node server.js

Go to webside URL from the server log, log in with your SmartThings account credentials, and choose a location. You should see a page with the location name as a header and button for each scene in that location. Clicking the button should execute the scene. If you don't see any buttons you may need to create some scenes using the SmartThings mobile app.

bflorian / api-app-minimal-example-js