Quick Start Guide to Testing the SmartThings API

The SmartThings API provides access to devices, the ability to create and manage routines, and more.

To begin exploring the SmartThings API you will need:

• A token for authentication
• A method to send HTTPS requests (curl, postman, etc)

Authentication/Tokens

For Testing & Personal Use: Personal Access Token (PAT)

For initial exploration, running personal scripts, or early testing, we recommend using a short-lived Personal Access Token (PAT). PATs are easy to generate and provide quick access to the API without the complexity of a full authorization flow.

For Integration Development: OAuth 2.0

Once you are developing an integration for other people to use, you must switch to OAuth 2.0. This standard, secure method allows your users to grant your service permission to access their SmartThings data.

This flow involves redirecting the user to SmartThings to approve the connection, after which your application receives an authorization code. Exchange this code for an access and refresh token pair, which allows you to make API calls on the user's behalf.

[Start Here] Personal Access Tokens

important

Personal access tokens are intended for short-term, initial access to the SmartThings APIs for testing and evaluation purposes. For long-term, production integrations, OAuth2.0 is the only approved authentication method.

A personal access token can be generated for any account you have the login credentials to by following these steps:

1. Navigate to https://account.smartthings.com/tokens in your web browser.
2. Sign in with your Samsung account.
3. Tap the “Generate new token” button, taking you to a “New Access Token” page.
4. Provide a name for the new token.
5. Select any functionality you wish to authorize for the token in the “Authorized Scopes” section.
6. Tap the “Generate Token” button when ready, and you’ll return to the “Personal access tokens” page.
7. Copy the newly generated token and keep it in a secure place. This is your only opportunity to retrieve the newly generated token value.

info

Personal Access Tokens are only valid for 24 hours unless otherwise stated.

[For Integration Development] OAuth2.0 Based Authentication

SmartThings API supports authentication via OAuth2.0 standards, which is the primary way to build a fully fledged integration, but can also be used for initial exploration if desired.

The clientId and clientSecret to be used in the authorization flow are obtained by creating an API App using the following steps:

1. Install the SmartThings CLI
2. In your command line, run the create app command:

   smartthings apps:create
3. Select OAuth-In App and follow the prompts, providing details for your app.
4. Select Finish and create OAuth-In SmartApp. You will be provided the details of your app along with your clientId and clientSecret. Be sure to copy these value and keep them in a secure place - this is the only time they will be provided.

Once your app is created and your OAuth server is configured as needed, you can use the OAuth values provided to initiate account linking via OAuth through the following flow:

1. Open the following URL in a web browser, filling in the placeholder values as needed. Information on SmartThings scopes can be found here.

   https://api.smartthings.com/oauth/authorize?client_id={clientId}&response_type=code&redirect_uri={yourRedirect}&scope={scopes}

2. Log in to your Samsung account and select a location to access.
3. After logging in, your OAuth server will receive a redirect with an authorization code.
4. Make a POST request to the following token endpoint:

   https://api.smartthings.com/oauth/token

5. When calling this endpoint, use basic auth for your authorization header using your clientId and clientSecret as the username and password. Include the following as x-www-form-urlencoded parameters:
   • grant_type - for initial token retrieval you will use a type of authorization_code
   • code - the code you received in the redirect from the authorization endpoint
   • redirect_uri - The same redirect uri used in the authorization step
   • client_id - the clientId of your integration

The response to your request will include your access and refresh tokens - linking is now complete.

tip

Access tokens are valid for 24 hours and can be refreshed by calling the token endpoint with a grant_type of refresh_token and providing your refresh token.

API Feature Overview

Once authenticated, you can make HTTPS requests to the SmartThings API endpoints documented here. The API provides a variety of functionality, but below are some of the most popular features used. Additional functionality, including available query parameters, are detailed in the full developer documentation.

Devices¹

GETList Devices

GETGet Device Description

GETGet Device Full Status

GETGet Device Component Status

GETGet Capability Status

POSTExecute Commands⁴

PUTUpdate a Device

DELDelete a Device

Routines²

GETList Rules

GETGet a Rule

POSTCreate a Rule

POSTExecute a Rule

PUTUpdate a Rule

DELDelete a Rule

Locations³

GETList Locations

GETGet a Location

POSTCreate a Location

PUTUpdate a Location

DELDelete a Location

Rooms

GETList Rooms

GETGet a Room

POSTCreate a Room

PUTUpdate a Room

DELDelete a Room

Modes

GETGet all Location Modes

GETGet a Mode

POSTCreate a Mode

DELDelete a Mode

GETGet Current Location Mode

PUTChange Location Current Mode

¹ Additional device endpoints for device profile, preference and capabilities, intended for device integrators are also available.

² Routines created in the mobile app will not be accessible in the API and Routines created via the API will not show in the mobile app.

³ Location endpoints are scope dependent - please ensure the token being used is appropriately scoped for your API app or location.

⁴ Multiple commands for the device can be provided in a single request.

Additional Resources

• SmartThings Base API Developer Documentation: https://developer.smartthings.com/docs/api/public
• OAuth 2.0 Spec: https://datatracker.ietf.org/doc/html/rfc6749
• SmartThings Base API PAT generator: https://account.smartthings.com/tokens
• SmartThings CLI: https://developer.smartthings.com/docs/sdks/cli
• SmartThings CLI App creation guide: https://github.com/SmartThingsCommunity/smartthings-cli?tab=readme-ov-file#smartthings-appscreate
• SmartThings Base API Scopes Documentation: https://developer.smartthings.com/docs/api/public#section/Authentication/OAuth2-scopes