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"
      }
    }
  }
}

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
        }
      }
    }
  }
}