Skip to main content

App-to-App Account Linking

✅ App-to-App Account Linking is supported on Android and iOS.

App-to-App Account Linking allows users to seamlessly link their account on your platform with their SmartThings account when your app and the SmartThings app are installed on the user's mobile device. Linking is initiated from within the SmartThings app.

When a user initiates the account linking process in the SmartThings app, the SmartThings app will call your app on the user's mobile device. Your app will then provide a method for authenticating the user.

If your app is not installed on the user's mobile device, the standard browser-based account linking flow is presented to the user.

Account Linking on Android

note

Communication between the SmartThings app and your app on an Android mobile device occurs through Android App Links. Read more about Android App Links in the Android documentation.

Prerequisites

For your Android app to handle App-to-App Account Linking, you must:

  • Add to your app's Manifest.xml file an Intent Filter for your website URIs and configure your app to use data from the SmartThings intent to send users to the right content in your app (deep linking). Read more about this process in the Android deep linking documentation.

  • Add verification for your deep links. Configure your app to request verification of app links, then publish a Digital Asset Links JSON file on your website to verify ownership through Google Search Console.

  • Use the following Intent Data function to receive incoming Android App Links. This will be needed to parse incoming Android App Link messages sent from the SmartThings app:

    private fun parseAndShowIncomingIntentInfo(uriData: Uri) {
    oauthLink = Uri.parse(uriData.toString())
    val uri = Uri.parse(uriData.toString())
    clientId = uri.getQueryParameter(CLIENT_ID)
    clientIdText.setText(clientId)
    redirectUri = uri.getQueryParameter(REDIRECT_URI)
    redirectUriText.setText(redirectUri)
    responseType = uri.getQueryParameter(RESPONSE_TYPE)
    responseText.setText(responseType)
    state = uri.getQueryParameter(STATE)
    stateText.setText(state)

    Log.i(TAG, "Data :: $uriData")
    Log.i(TAG, "client_id :: $clientId")
    Log.i(TAG, "redirect_uri :: $redirectUri")
    Log.i(TAG, "responseType :: $responseType")
    Log.i(TAG, "state :: $state")
    }

SmartThings will send to your app an Android App Link. An example may look like:

https://www.smartthings.com/test-c2c-App-to-App-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-App-to-App-account-linking

The Android App Link sent by the SmartThings app will contain the following components:

{Your App Scheme}{Your App Domain Host}/{Your App Domain Path}?client_id={Your ClientId}&response_type={Response Value}&state={Unique State Value}&redirect_uri={link used to communicate back to SmartThings App}
  • Your app scheme (usually in the form of https://).
  • Your app domain host. This is the domain host where your Digital Asset Links file is hosted. For example, SmartThings' domain host with scheme is https://www.smartthings.com
  • Your Client ID. This is the unique ID you will provide to SmartThings for your app to verify that the web link being sent by the SmartThings app is a trusted Android App Link. For security reasons, the sent clientId should always be validated by your app to verify the authenticity of incoming Android App Links.
    • The clientId key to parse from the Android App Link is client_id.
  • Response type. The value of the key that should be sent back to SmartThings on successful authentication.
    • This value is generally code. Always parse the value and store it so that your app can use it when building the Android App Link that will communicate back to the SmartThings app.
    • The ResponseType key to parse from the Android App Link is response_type
  • A unique session ID called state. This session ID is generated by SmartThings to uniquely identify the account linking session request. Your app should send the state value back to SmartThings upon successful or unsuccessful authentication.
    • Account linking cannot be sufficiently validated and completed on the SmartThings side if this state value is not passed back to the SmartThings app.
    • The state key to parse from the Android App Link is state.
  • Redirect URI. This is the encoded Android App Link domain and path that your app should use to send the authCode or error back to the SmartThings app with the necessary data after either authentication success or failure.
    • The redirect URI is encoded and must be decoded before use.
    • The redirect URI uses the following form when decoded using the UTF-8 standard: {SmartThings App Scheme}{SmartThings App Domain Host}/{SmartThings App Domain Path} https://www.smartthings.com/c2c-app-to-app-account-linking
    • Any query parameters such as authcode and state need to be appended as parameters to the above URL as code and state.

Once your app receives the Android App Link from the SmartThings app to initiate account linking, your app should attempt to authenticate the user to your system. This is often done by showing a sign-in or login screen to the user.

info
  • If authentication is successful in your app, you must generate an authcode.

  • If authentication fails in your app, you must generate an error.

Once user authentication has been deemed either successful or unsuccessful by you, the appropriate state must be passed back to the SmartThings app using the Android App Link callback.

To create the Android App Link callback from your app:

  1. Parse out the redirect URI from the incoming Android App Link from the SmartThings app and decode it using UTF-8. The result should look something like: https://www.smartthings.com/c2c-app-to-app-account-linking
  2. Append the state URL parameter to this URL. Use the state key with the value being the value of the state parameter sent by the SmartThings app to your app via Android App Link. For example, if the SmartThings app sent the following Android App Link to your app:
https://www.smartthings.com/test-c2c-app-to-app-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-app-to-app-account-linking

Then your app should parse out the value of state as:

eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD

and send this value back as the state value, with key state, when sending the Android App Link back to the SmartThings app.

A sample Android App Link at this point should look like this:

https://www.smartthings.com/c2c-app-to-app-account-linking?state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD
3a: If User Authentication Is Successful

If user authentication is successful, add your app's generated authcode as a parameter to the Android App Link URL. The key of the parameter should be the value of response_type from the incoming link from the SmartThings app.

For example, if the incoming Android App Link from the SmartThings app is:

https://www.smartthings.com/test-c2c-app-to-app-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-app-to-app-account-linking

then the callback to the SmartThings app should resemble the example below. In this case, the authcode key is code and the value is 1234 as that is the example response_type parameter value of the link sent by the SmartThings app.

https://www.smartthings.com/c2c-app-to-app-account-linking?state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&code=1234
3b: If User Authentication Fails

If user authentication fails, add your generated error as a parameter to the universal link URL. The value should be a string that is either any error code string or any string defining the error. The error parameter key should be error.

For example, if the incoming Android App Link from the SmartThings app is:

https://www.smartthings.com/test-c2c-app-to-app-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-app-to-app-account-linking

then the failure case Android App Link that will callback to the SmartThings app should resemble the example below. The example error value here is unauthorized:

https://www.smartthings.com/c2c-app-to-app-account-linking?state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&error=unauthorized
  1. Once the parameters for either the success case or the failure case have been added, the Android App Link is now fully built and can be sent to the SmartThings app with the state and either the authcode or the error.

  2. Once the Android App Link is sent back to the SmartThings app from your app with the state and authcode or error, the SmartThings app will handle the rest of the account linking process with your app and cloud services.

Account Linking on iOS

note

Communication between the SmartThings app and your app on an iOS mobile device occurs through universal links. Read more about universal links in the iOS developer documentation.

Prerequisites

For your iOS app to handle App-to-App Linking and receive universal links from the SmartThings app, you must:

  • Add the Associated Domains capability to your iOS app and to your iOS provisioning profile used in building your app.

  • Register for universal linking behavior. Do this by registering for the AppLinks:{Your Domain} domain in the Associated Domains capability section of your iOS app's project Signing & Capabilities section.

  • Create your own Apple-App-site-association file. This allows the SmartThings app to reach your app via universal linking.

  • Use the following SceneDelegate method to receive incoming universal links. This is needed to parse incoming universal link messages sent from the SmartThings app.

    final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    // Use this method to optionally configure and attach the UIWindow `window` to the provided UIWindowScene `scene`.
    // If using a storyboard, the `window` property will automatically be initialized and attached to the scene.
    // This delegate does not imply the connecting scene or session are new (see `application:configurationForConnectingSceneSession` instead).
    if let userActivity = connectionOptions.userActivities.first {
    self.scene(scene, continue:userActivity)
    }
    guard let _ = (scene as? UIWindowScene) else { return }
    }
    }
  • Verify that the clientId being passed to your app is the client ID that you registered with SmartThings:

    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
    let webpageURL = userActivity.webpageURL else {
    print ("AppCoordinator continueUserActivity = unhandled userActivity received: \(userActivity)")
    return
    }

    // parse url components
    let urlComponents = urlComponents(url: webpageURL, resolvingAgainstBaseURL: false)

    let clientId = urlComponents?
    .queryItems?
    .first(where: { $0.name == clientIdKey })?
    .value

SmartThings will send to your app a universal link such as this:

https://www.smartthings.com/test-c2c-App-to-App-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-App-to-App-account-linking

The universal link sent by the SmartThings app will contain the following components:

{Your App Scheme}{Your App Domain Host}/{Your App Domain Path}?client_id={Your ClientId}&response_type={Response Value}&state={Unique State Value}&redirect_uri={Universal link used to communicate back to SmartThings App}
  • Your app scheme, usually in the form of https://.
  • Your app domain host. This is the domain host where your Apple-App-site-association file is hosted. For example, SmartThings' domain host with scheme is be https://www.smartthings.com/.
  • Your Client ID. This is the unique ID you will provide to SmartThings for your app to verify that the universal link being sent by the SmartThings app is a trusted universal link. For security reasons, the sent clientId should always be validated by your app to verify the authenticity of incoming universal links.
    • clientId key to parse from the universal link is client_id.
  • Response type. The value of the key that should be sent back to SmartThings on successful authentication.
    • This value is generally code. Always parse the value and store it so that your app can use it when building the universal link that will communicate back to the SmartThings app.
    • ResponseType key to parse from the Android App Link is response_type
  • A unique session ID called state. This session ID is generated by SmartThings to uniquely identify the account linking session request. Your app should send the state value back to SmartThings upon successful or unsuccessful authentication.
    • Account linking cannot be sufficiently validated and completed on the SmartThings side if this state value is not passed back to the SmartThings app.
    • State key to parse from the universal link is state.
  • Redirect URI. This is the encoded universal link domain and path that your app should use to send the authCode or error back to the SmartThings app with the necessary data after either authentication success or failure.
    • The redirect URI is encoded and must be decoded before use.
    • The redirect URI uses the following form when decoded using the UTF-8 standard: {SmartThings App Scheme}{SmartThings App Domain Host}/{SmartThings App Domain Path} https://www.smartthings.com/c2c-app-to-app-account-linking
    • Any query parameters such as authcode and state need to be appended as parameters to the above URL.

Once your app receives the universal link from the SmartThings app to initiate account linking, your app should attempt to authenticate the user in your system. This is often done by showing a sign-in screen to the user.

info
  • If authentication is successful in your app, you must generate an authcode.

  • If authentication fails in your app, you must generate an error.

Once user authentication has been deemed either successful or unsuccessful by you, the appropriate state must be passed back to the SmartThings app using the callback universal link.

To create the universal link callback:

  1. Parse out the redirect URI from the incoming universal link from the SmartThings app. Decode it using UTF-8. The result should look something like this:
https://www.smartthings.com/c2c-App-to-App-account-linking
  1. Append the state url parameter to the received URL. Use the state key with the value being the value of the state parameter sent by the SmartThings app to your app via the universal link. For example, if the SmartThings app sent the following universal link to your app:
https://www.smartthings.com/test-c2c-App-to-App-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-App-to-App-account-linking

Then your app should parse out the value of state as:

eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD

and send this value back as the state value, with key state when sending the universal link back to the SmartThings app.

A sample universal link at this point should look like:

https://www.smartthings.com/test-c2c-app-to-app-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%253A%252F%252Fwww.smartthings.com%252Fc2c-app-to-app-account-linking
3a: If User Authentication Is Successful

If user authentication is successful, add your app's generated authcode as a parameter to the universal link URL. The key of the parameter should be the value of response_type from the incoming link from the SmartThings app.

For example, if the incoming universal link from the SmartApp is:

https://www.smartthings.com/test-c2c-App-to-App-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-App-to-App-account-linking

then the callback to the SmartThings app should resemble the example below. In this case the authcode key is code and the value is 1234 as that is the example response_type parameter value of the universal link sent by the SmartThings app.

https://www.smartthings.com/c2c-App-to-App-account-linking?state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&code=1234
3b: If User Authentication Fails

If user authentication fails, add your generated error as a parameter to the universal link URL. the value should be a string that is either any error code string or any string defining the error. The error parameter key should be error.

For example, if the incoming universal link from the SmartThings app is:

https://www.smartthings.com/test-c2c-App-to-App-account-linking?client_id=1e92f9fe-4543-4588-813c-ee31a7fc682c&response_type=code&state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&redirect_uri=https%3A%2F%2Fwww.smartthings.com%2Fc2c-App-to-App-account-linking

then the failure case universal link that will callback to the SmartThings app should look like the example below, with an example error value of unauthorized:

https://www.smartthings.com/c2c-App-to-App-account-linking?state=eyJhbGciOiJIUzM4NCJ9.MGZlYWUwOWMtYWJmOS00Y2VjLTlhMGQtZGJiZjJmMTE4OTNlOnZpcGVyXzRjYjFlNzQwLWQ0MTUtMTFlOS04MjUwLThmNDk4MjRhOTg3NjoxNjMwMTExMDc3OTMwOkE2MzgyMzI4LTZDQTItNDhGNC1CNzg3LThDMjNCMTgwRUE5Nzplbjo.M491ukTlzqCl57it_x2aGhhAPmV4CEmFNHCsU46r1w6UuZ4x1-Fir0o8wb8sgfPD&error=unauthorized
  1. Once the parameters for either the success case or the failure case have been added, the universal link is now fully built and can be sent to the SmartThings app with the state and either the authcode or the error.

  2. After the universal link is sent back to the SmartThings app from your app with the state and authcode or error, the SmartThings app will handle the rest of the account linking process with your app and cloud services.