OAuth integrations

SmartThings uses OAuth2 for authentication. To integrate a third-party application with SmartThings, first submit a request. Once approved, you can enable users of your platform to interact with SmartThings Cloud through your application.

This article describes the high-level process of integrating with the SmartThings authentication flow:

  • Registering your application, which includes defining the OAuth permission scopes and the redirect URIs used in the Authorization Code flow.
  • Implementing the OAuth endpoints in your application.

Request to integrate third-party applications

You can request to integrate third-party applications using this form.

Sequence

Authorization from your cloud service to SmartThings Cloud is illustrated below.

SmartThings OAuth flow

A user taps on a "My SmartThings" icon in your application to begin the authorization flow with SmartThings, logs into SmartThings, and grants the requested permissions to SmartThings.

Register your application

From the project creation page on Developer Workspace, select API Access.

  • Name your application and click CREATE PROJECT.
  • In the Develop menu, click Register An Application to register your application. The Hosting tab will open.
  • Enter a Client Name to be shown on the permissions page during authentication.
  • Enter an Application Name that is globally unique.
  • Enter an Application Display Name to be shown in the SmartThings app.
  • Enter an Application Description to be shown in the SmartThings app.
  • Enter the Redirection URIs to be used in the authentication flow.
  • Click Next to open the App Scope tab.
  • Select the OAuth2 scopes required for the application.
  • Click SAVE.

After saving the above information, you can return to the Register An Application page to access the client ID and client secret for this application. You will need this information in the authentication flow.

External application info

Authentication flow

A third-party application must authenticate with SmartThings using the Authorization Code flow.

A user first taps on a "My SmartThings" icon in your application. Your application must then redirect the user to the SmartThings accounts server by calling an OAuth endpoint.

When the user grants permissions, they will be redirected to your server (at a specified redirect_uri) with an authorization code. For example:

https://my-development-app.com/oauth/callback?code=0ee7fcd0abed470182b02cd649ec1c98&state=abcdefgh

You can exchange this code for an access token in a subsequent POST request to SmartThings.

SmartThings responds with a JSON body containing the access token and refresh token:

{
  "access_token": "a605e9d7-46a9-d867-955c-74063dooc4e9",
  "token_type": "bearer",
  "refresh_token": "5d8rr9d7-a988-0a45-955c-74068fh8ur0l",
  "expires_in": 299,
  "scope": "x:devices:* r:devices:*"
}

Cross-site request forgery protection

To prevent cross-site request forgery (CSRF), as detailed in the OAuth specification, the SmartThings OAuth server supports the state variable across requests.