Skip to main content

Get Started with the Admin API

Start here if you are a developer or integrator looking to use our API to pull your White Label product data into your business or service for consumption (e.g. for Billing system integration).

  • API Overview
  • Getting Started Quickly
  • API Reference

API Overview​

The myDevices API is a RESTful API. REST is a lightweight, stateless web service standard that myDevices IoT provides to our partners so that they may access and consume their data. Our REST API is secured with OAuth2 standard, which offers increased security by using JWT access tokens. In addition to Authorization and Authentication mechanism, we encrypt all transport communications with TLS/SSL endpoints.

info

There are two API routes available giving you high-level information on your white label accounts and detailed, low-level, account-specific data:

danger

Hostname deprecation warning: api.iotinabox.com is not longer supported, please use api.mydevices.com

  • Admin API: The /v1.0/admin/ routes. In most cases, the Admin-level API queries can be used to access high-level data for your white label application as a whole.

Examples of API queries here are:

  • List all Companies or Locations under your white label
  • List all Devices under your white label
  • List all Users under your white label
  • Get Owner/Admin for one of your customer's locations

All the other routes: Outside of the /v1.0/admin/ routes, we also have additional routes which provide access in case you need detailed data specific to an account.

Examples of queries found within these additional API routes are:

  • Query user's account for Report data
  • Query user's account for Current or Historical device readings
  • Query user's account for Alert configuration & Alert data

Documentation and examples on using these additional routes is found in our separate Cloud API. Please be sure to read the important notes below before you use those routes as this often trips up new API users.

caution

These other (non-Admin) routes are meant to be used by logged in users and tokens are checked to make sure there's a user id associated to access_token as these routes should not return data from other users. Therefore, you are not using the same token obtained using the high-level Admin API calls such as discussed in this article. Instead, you must follow the instructions shown in the Cloud API and its examples on how to obtain a separate token for accessing data from a specific user account.

Getting Started Quickly​

This guide will quickly take you through the steps needed to setup and start using our API. During the course of the guide we will obtain all the information needed to use the API as well as go through how to authorize and start making calls to verify things are working.

Obtain the API Keys for the account.​

Before you can use the API you will need to obtain your API credentials. In order for your service to successfully connect with myDevices and access data, you will need to provide these keys when using the API.

Authorize yourself using OAuth2.​

The myDevices API is secured with the OAuth2 standard, which offers increased security by using JWT access tokens. Before you can utilize the API you must first successfully complete the Authorization and Authentication requirements and obtain an access token. Once your application has an access token, it may use the token to make API calls, limited to the scope of access, until the token expires or is revoked.

alt text Remember to insert the appropriate values (highlighted between " ** ** " below) from your account and the API tab in the console.

Tip: You can copy the auth call shown on the API tab in the console - it has all this information populated for you.

curl --request POST \
--url https://auth.mydevices.com/auth/realms/**YourRealm**/protocol/openid-connect/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials&client_id=**YourClientID**&client_secret=**YourClientSecret**'

Example response (token info abbreviated):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2...",
  "expires_in": 86400,
  "refresh_expires_in": 172800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2...",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "91322891-2662-4b3c-8655-9214a7596e2c",
  "scope": "profile email"
}