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

Follow these steps to register your application on Developer Workspace.

After registering your application, you can use Developer Workspace to access its client ID and client secret. You will need this information in the authentication flow.

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.