Onboarding Devices

IoT devices are onboarded into the Yonomi IoT platform by the account linking workflow. This workflow consists of:

  • Identifying the Yonomi integration corresponding to the device’s IoT backend for cloud control (referred to as the 3rd party account)
  • Generating a URL for Yonomi to request device control permissions from the 3rd party account
  • The user and their client completing the OAuth 2.0 Authorization Code Grant flow
  • Yonomi completing a device discovery process

Account Linking

End-users connect their IoT devices via Yonomi’s account linking flow.

To get a list of available Yonomi integrations, query for integrations with this GraphQL Query:

query getAllIntegrations {
  integrations {
    edges {
      node {
        id
        displayName
      }
    }
  }
}

Create an account linking URL

To kick off account linking, use the generateAccountLinkingUrl GraphQL mutation and supply the ID of the Yonomi integration.

mutation generateAccountLinkingUrl ($integrationId: ID!) {
  generateAccountLinkingUrl(integrationId: $integrationId) {
    url
    expiresAt
    integration {
      id
      displayName
    }
  }
}

A response may look like:

{
  "data": {
    "generateAccountLinkingUrl": {
      "url": "https://platform.yonomi.cloud/integrations/accounts/connect?contextToken=eyJhbG...",
      "expiresAt": "2021-06-10T20:53:47.159Z",
      "integration": {
        "id": "a644abd9-b755-4af7-896a-8877753570b9",
        "displayName": "3rd party integration"
      }
    }
  }
}

Using the account linking URL

Let’s take a closer look at the returned url.

  • URL endpoint: https://platform.yonomi.cloud/integrations/connect
  • Query Parameter: contextToken=eyJhbG...

The query parameter contextToken is a one-time token that captures the account linking context. This context is used to persist the “authorization session” while the user is entering credentials and being redirected back to the Yonomi IoT Platform.

Load the URL in a web view supported by your application to allow the user to authorize Yonomi to control their devices.

The account linking URL is a short-lived one-time URL. The expiresAt field indicates the timestamp when the URL will expire, and you will need to request a new account linking URL.

OAuth 2.0 Authorization Code Grant Flow

Following this link, the end-user will now go through a series of redirects that will eventually result in a persisted linked account on the Yonomi IoT Platform.

First, they will be redirected to the 3rd party login page. The user will put in their credentials.

After submitting the 3rd party’s authorization forms, the user will go through several redirects, all facilitated via the OAuth 2.0 spec, ultimately resulting in a final redirect back to a configured final redirect URL. After successfully completing this workflow, Yonomi will create a record of the user’s successfully linked account. You can query for the user’s linked account with the following GraphQL query.

query linkedAccounts {
  me {
    id
    lastActivityAt
    firstActivityAt
    linkedAccounts {
      edges {
        node {
          id
          status
          createdAt
          integration {
            id
            displayName
          }
        }
      }
    }
  }
}

For more detailed information on OAuth 2.0, see the official OAuth 2.0 spec.

Device Discovery

After the user has a fully authorized their linked account, Yonomi will automatically kick off a device discovery process. In this process the user’s 3rd party connected devices will be discovered by the platform.

Query for devices associated with the linked account via:

query myDevices {
  me {
    devices (linkedAccountId: $linkedAccountId) {
      pageInfo { hasNextPage }
      edges {
        node {
          ... DeviceDetails
        }
      }
    }
  }
}

Account Relinking

Accounts can get into a NOT_AUTHORIZED state at times. This could happen for multiple reasons, depending on the first or third-party integration created by Yonomi. When this happens, the platform provides the user with a method to relink the account. Developers should utilize the account relinking workflow to reauthorize a linked account. This is preferable to creating a new account linking, which would create a completely new object in the platform with all new linked account IDs and device IDs.

To kick-off account relinking workflow, use the generateAccountRelinkingUrl GraphQL mutation and supply the account ID in the NOT_AUTHORIZED state.

mutation generateAccountRelinkingUrl ($linkedAccountId: ID!) {
   generateAccountRelinkingUrl(linkedAccountId: $linkedAccountId) {
   url
   expiresAt
   integration {
     id
     displayName
   }
 }
}

A response may look like this:

{
 "data": {
   "generateAccountRelinkingUrl": {
     "url": "https://platform.yonomi.cloud/integrations/accounts/connect?contextToken=eyJ.....",
     "expiresAt": "2022-08-02T19:58:46.747Z",
     "integration": {
       "id": "a644abd9-b755-4af7-896a-8877753570b9",
       "displayName": "3rd party integration"
     }
   }
 }
}

From here, the account relinking workflow will be the same as the account linking workflow. Refer to this segment of the document.

← Introduction to GraphQL
Listing Devices →