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.

NOTE

You must have a company MNID to have your request approved.

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

Note: Make sure you have a Samsung account.

Use Developer Workspace or the SmartThings API to register your application. The Authorized Scopes you select must include at minimum Write all apps.

After registering your application, the SmartThings platform provides a client ID and client secret for your application. 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:*"
}

Access tokens expire in 24 hours. See Authorization and Permissions on how to use the refresh token.

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.