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.
You can request to integrate third-party applications using this form.
You must be a member of an organization to have your request approved.
Authorization from your cloud service to SmartThings Cloud is illustrated below.
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.
Make sure you have a Samsung account.
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.
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:
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 tokens expire in 24 hours. See Authorization and Permissions on how to use the refresh token.
To prevent cross-site request forgery (CSRF), as detailed in the OAuth specification, the SmartThings OAuth server supports the
state variable across requests.