Cover image showing a configuration that integrates smart home devices via API, from installing the SmartThings CLI through OAuth authentication

Overview

SmartThings is an IoT platform provided by Samsung Electronics.

It allows you to connect and control smart home devices such as lights, air conditioners, TVs, sensors, plugs, and door locks under a single account and Location.

With the SmartThings API, you can automate tasks that were previously only possible through the SmartThings app from external services or personal servers.

For example, you can use the REST API or SmartThings CLI to retrieve registered device lists, check device status, control power, set temperatures, and configure automation conditions.

This article covers the basic preparation steps for SmartThings API integration. The overall flow is as follows:

  1. Prepare a SmartThings account and devices.
  2. Install the SmartThings CLI.
  3. Complete account authentication by logging in through the CLI.
  4. Create an app or token required for API calls.
  5. Verify the device list and permission scopes.
  6. Call the SmartThings API from an external application.

For personal testing or simple automation, you can get started quickly with a Personal Access Token (PAT).

However, for long-running services or apps that require user authentication, OAuth-based integration is more appropriate.

Installation

To begin SmartThings API integration, first install the SmartThings CLI.

The CLI is an official tool that allows you to use the SmartThings API from the terminal.

You can use the CLI to handle tasks such as app creation, authentication, device listing, and command execution.

Installing on macOS with Homebrew

On macOS, using Homebrew is the simplest method.

1# Trust the SmartThings Community formula
2brew trust --formula smartthingscommunity/smartthings/smartthings-prerelease
3
4# Install SmartThings CLI
5brew install smartthingscommunity/smartthings/smartthings
6
7# Verify installation
8smartthings --version

brew trust registers the formula provided by the SmartThings Community tap as trusted. After that, brew install installs the SmartThings CLI.

Once the installation is complete, verify it with the smartthings --version command. If version information is displayed, the CLI is ready to use.

Installing on Windows

On Windows, downloading and using the SmartThings CLI executable is the recommended approach.

Download the Windows archive from the GitHub Releases page, then place the executable in a directory included in PATH.

  1. Go to the SmartThings CLI GitHub Releases page.
  2. Download the Windows archive.
  3. Extract the archive.
  4. Copy the smartthings.exe file to your preferred directory.
  5. Add that directory to the Windows PATH environment variable.
  6. Open a new PowerShell or Command Prompt window and verify the installation.
1smartthings --version

If the smartthings --version command displays version information, the installation is complete. If you get a “command not found” error, check that the directory containing smartthings.exe is properly registered in PATH.

Installing with npm in a Node.js Environment

If Node.js is already installed in your development environment, you can install the SmartThings CLI via npm. This method works across Windows, macOS, and Linux.

1npm install -g @smartthings/cli
2
3smartthings --version

The npm method is convenient in Node.js-based development environments. If you prefer not to add a Node.js dependency, using the OS-specific executable or Homebrew installation is simpler.

Installing on Linux

On Linux, download the SmartThings CLI release file, grant execution permissions, and place it in the system path. This is a general installation flow that works regardless of the distribution.

 1# Create installation directory
 2mkdir -p ~/bin
 3
 4# Download and extract the SmartThings CLI Linux file
 5# Adjust the actual filename and URL to match the latest version on the [GitHub Releases page](https://github.com/SmartThingsCommunity/smartthings-cli/releases).
 6tar -xzf smartthings-linux-x64.tar.gz
 7
 8# Move the executable
 9mv smartthings ~/bin/
10
11# Grant execution permission
12chmod +x ~/bin/smartthings
13
14# Register PATH
15echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
16source ~/.bashrc
17
18# Verify installation
19smartthings --version

If you use zsh as your shell, register the PATH in ~/.zshrc instead of ~/.bashrc.

1echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
2source ~/.zshrc

In server environments, you can place it in /usr/local/bin to make it available to all user accounts.

1sudo mv smartthings /usr/local/bin/
2sudo chmod +x /usr/local/bin/smartthings
3
4smartthings --version

App Creation and Authentication

To prepare for OAuth-based integration, create an app using the SmartThings CLI.

1smartthings apps:create

Running this command initiates a procedure to enter information such as the app name, description, permission scopes, and redirect URL.

During this process, you register the app information that will be used for API calls.

 1smartthings apps:create
 2✔ What kind of app do you want to create? (Currently, only OAuth-In apps are
 3supported.) OAuth-In App
 4
 5More information on writing SmartApps can be found at
 6  https://developer.smartthings.com/docs/connected-services/smartapp-basics
 7
 8✔ Display Name test-app
 9✔ Description test
10✔ Icon Image URL (optional)
11✔ Target URL (optional)
12
13More information on OAuth 2 Scopes can be found at:
14  https://www.oauth.com/oauth2-servers/scope/
15
16To determine which scopes you need for the application, see documentation for the individual endpoints you will use in your app:
17  https://developer.smartthings.com/docs/api/public/
18
19✔ Select Scopes. r:devices:*, w:devices:*, x:devices:*, r:hubs:*, r:locations:*,
20w:locations:*, x:locations:*, r:scenes:*, x:scenes:*, r:rules:*, w:rules:*, r:installedapps,
21w:installedapps
22✔ Add or edit Redirect URIs. Add Redirect URI.
23✔ Redirect URI (? for help) https://httpbin.org/get
24✔ Add or edit Redirect URIs. Finish editing Redirect URIs.
25✔ Choose an action. Finish and create OAuth-In SmartApp.
26Basic App Data:
27───────────────────────────────────────────────────────────────
28 Display Name     test-app
29 App Id           72b65205-14ef-48cb-94eb-xxxxxxxxxxxx
30 App Name         testapp-91735007-4498-4b3a-96f0-xxxxxxxxxxxx
31 Description      test
32 Single Instance  true
33 Classifications  CONNECTED_SERVICE
34 App Type         API_ONLY
35───────────────────────────────────────────────────────────────
36
37
38OAuth Info (you will not be able to see the OAuth info again so please save it now!):
39───────────────────────────────────────────────────────────────
40 OAuth Client Id      19c1fcbf-988c-4bc0-bccf-xxxxxxxxxxxx
41 OAuth Client Secret  1b95dfcf-2227-4b98-9547-xxxxxxxxxxxx
42───────────────────────────────────────────────────────────────

API Usage

Choosing an API Integration Method

There are two main ways to call the SmartThings API:

  • Personal Access Token (PAT)
    • Suitable for personal testing and simple automation.
    • Token generation is straightforward.
    • You select and issue the required permission scopes directly.
    • May not be suitable for long-running production services.
  • OAuth App
    • Suitable for external applications or services that require user authentication.
    • Operates on a model where users approve permissions.
    • Can be managed with access tokens and refresh tokens.
    • If building a service for distribution, consider this method first.

OAuth Authentication and Token Issuance

This method is for development purposes. In production environments, it is safer to use an HTTPS callback URL that you control directly.

This step is performed after obtaining the OAuth Client ID and OAuth Client Secret via smartthings apps:create.

If you are not setting up a separate web server, register a temporary callback URL as the Redirect URI.

1https://httpbin.org/get

The redirect_uri in the authorization URL and the redirect_uri in the token request must exactly match the value registered during app creation.

1https://api.smartthings.com/oauth/authorize?response_type=code&client_id=<client-id>&redirect_uri=https%3A%2F%2Fhttpbin.org%2Fget&scope=<scope>

After approval, copy the code value from the redirected URL and use it in the token issuance request.

1curl -X POST "https://api.smartthings.com/oauth/token" \
2  -H "Content-Type: application/x-www-form-urlencoded" \
3  -u "<client-id>:<client-secret>" \
4  -d "grant_type=authorization_code" \
5  -d "code=<authorization-code>" \
6  -d "redirect_uri=https://httpbin.org/get"

When actually using the SmartThings API, you should refer to the official Samsung SmartThings API documentation to verify endpoints, permission scopes, and request/response formats.

The official documentation provides APIs for major resources such as Devices, Locations, Scenes, Rules, and Installed Apps. When implementing device control, the typical flow is to first retrieve the device list, check the capability and command structure of each device, and then call the command API.

Use the following links for reference documentation:

For simple tests, it is recommended to start with curl or Postman. When applying to actual services or automation scripts, select only the necessary permissions as scopes and store tokens securely.

1curl -X GET "https://api.smartthings.com/v1/devices" \
2  -H "Authorization: Bearer <access-token>"

The above request retrieves the list of devices connected to the account. After checking the device ID and capability information in the response, you can extend to status queries or command execution APIs.

CLI Usage

Use this when directly controlling devices with the previously installed CLI.

Login

1smartthings login

Running this command initiates a browser-based authentication process.

After logging in with your Samsung account and approving the permission request, the CLI can access the resources of your SmartThings account.

Once login is complete, verify the registered locations with the following command:

1smartthings locations

Check the list of connected devices with the following command:

1smartthings devices

If you need detailed information about a specific device, specify the device ID.

1smartthings devices <device-id>

Conclusion

The OAuth Client ID and Client Secret issued at this point cannot be retrieved again, so you must save them separately.

In test environments where you are not running a web server, you can use a temporary Redirect URI such as https://httpbin.org/get.

However, the Redirect URI registered during app creation, the authorization URL, and the redirect_uri value used in the token issuance request must all be identical.

After token issuance is complete, refer to the SmartThings Public API documentation to identify the required endpoints and scopes.

The typical flow is: device list retrieval, capability verification, status query, and command execution, in that order.

The CLI is useful for verifying installation and performing simple device queries.

For actual services or automation scripts, it is important to select only the necessary permissions based on the API documentation and to securely manage tokens and Client Secrets.