Get Started with the Admin API

This guide will walk you through making your first Admin API calls. In 5 minutes, you'll authenticate and query your white label data.

Prerequisites

Before you begin, ensure you have:

• A myDevices White Label account
• Admin access to the myDevices console
• A tool for making API calls (curl, Postman, or similar)

API Overview

The myDevices Admin API is a RESTful API secured with OAuth2. Key characteristics:

• Protocol: REST over HTTPS
• Authentication: OAuth2 with JWT tokens
• Response Format: JSON
• Base URL: https://api.mydevices.com

Hostname Update

The legacy hostname api.iotinabox.com is deprecated. Please use api.mydevices.com for all API calls.

Understanding API Routes

The myDevices API provides two types of routes based on your data access needs:

Admin Routes (/v1.0/admin/*)

Use for: Cross-user operations and white label management

These routes allow you to query data across your entire white label application:

• List all Companies or Locations
• Query all Devices across customers
• Manage Users and permissions
• Access aggregated data for billing and reporting

Authentication: Client credentials flow (this guide)

User-Specific Routes (all other routes)

Use for: Individual user data access

These routes require user context and are used for:

• Querying a user's device readings
• Accessing user-specific reports
• Managing user's alert configurations
• User-facing dashboards and applications

Authentication: Resource owner password flow Documentation: See User-Level Authentication

Important

Admin tokens will not work with user-specific routes. User-specific routes validate that a user ID is associated with the access token. You must use user-level authentication for these endpoints.

Step 1: Obtain Your API Credentials

1. Log into the myDevices console
2. Navigate to Admin API from the menu
3. Go to the API section
4. Click Show to reveal your Client Secret
5. Copy these three values:
   • Realm (e.g., my-company)
   • Client ID (e.g., billing-service)
   • Client Secret (e.g., a1b2c3d4...)

Pro Tip

The console's API tab shows a ready-to-use curl command with your credentials pre-populated. You can copy it directly!

Step 2: Authenticate and Get an Access Token

Use the OAuth2 Client Credentials flow to obtain an access token:

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

Replace YOUR_REALM, YOUR_CLIENT_ID, and YOUR_CLIENT_SECRET with your actual credentials.

Example Response

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

The access_token is valid for 24 hours (86400 seconds). Save it for the next steps.

Token Lifespan

Access tokens expire after 24 hours. Use the refresh_token to obtain a new access token without re-authenticating, or simply re-authenticate when needed.

Step 3: Make Your First API Call

Now that you have an access token, let's query your companies. This is a common first step for billing integrations.

Get All Companies

curl --request GET \
  --url https://api.mydevices.com/v1.0/admin/companies \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json'

Replace YOUR_ACCESS_TOKEN with the token from Step 2.

Example Response

{
  "count": 2,
  "limit": 50,
  "page": 0,
  "rows": [
    {
      "id": 1265,
      "name": "Acme Corporation",
      "industry": "[\"Manufacturing\"]",
      "address": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US",
      "user_id": "9c60c56b-d468-4f75-ac76-7670bf425375",
      "application_id": "my-white-label",
      "created_at": "2023-01-15T10:30:00.000Z",
      "updated_at": "2023-06-20T14:22:00.000Z"
    },
    {
      "id": 1266,
      "name": "Beta Industries",
      "industry": "[\"Technology\"]",
      "address": "456 Tech Blvd",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US",
      "user_id": "7a45b23c-f891-4e56-bc34-1234567890ab",
      "application_id": "my-white-label",
      "created_at": "2023-02-10T09:15:00.000Z",
      "updated_at": "2023-07-01T11:45:00.000Z"
    }
  ]
}

Success! You've queried your companies. Each company includes:

• Basic info (name, address, industry)
• user_id - The owner/admin user for billing contacts
• application_id - Your white label application

Step 4: Query Devices for a Company

Let's get more specific by querying devices for one of your companies.

Get Devices by Company

Using company_id from the previous response:

curl --request GET \
  --url 'https://api.mydevices.com/v1.0/admin/things?company_id=1265&page=0&limit=50' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json'

Example Response

{
  "count": 3,
  "limit": 50,
  "page": 0,
  "rows": [
    {
      "id": "75722a70-711c-11e9-9fd4-e73c33d2d42c",
      "thing_name": "Temperature Sensor - Warehouse A",
      "hardware_id": "eui-00001c497bb44a5c",
      "device_type_id": "36c52526-e689-11e7-80c1-9a214cf093ce",
      "thing_type": 1,
      "status": 0,
      "enabled": 1,
      "company_id": 1265,
      "location_id": 890,
      "user_id": "9c60c56b-d468-4f75-ac76-7670bf425375",
      "created_at": "2023-03-01T12:00:00.000Z",
      "updated_at": "2023-08-15T10:30:00.000Z"
    }
  ]
}

This response shows you have 3 devices for company 1265. Key fields:

• id (cayenne_id) - Used for admin device operations
• hardware_id - Physical device identifier (e.g., EUI)
• status - 0: Activated, 1: Deactivated
• thing_type - 0: Gateway, 1: Device

Step 5: Get Device Count (for Billing)

A common use case is counting devices per company for billing:

curl --request GET \
  --url 'https://api.mydevices.com/v1.0/admin/things/count?company_id=1265' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json'

Example Response

{
  "count": 3
}

Perfect for billing integrations - you now know this company has 3 devices.

Complete Example Script

Here's a complete bash script that ties everything together:

#!/bin/bash

# Configuration
REALM="your-realm"
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"

# Step 1: Authenticate
echo "Authenticating..."
TOKEN_RESPONSE=$(curl -s --request POST \
  --url "https://auth.mydevices.com/auth/realms/${REALM}/protocol/openid-connect/token" \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data "grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}")

ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.access_token')

if [ "$ACCESS_TOKEN" == "null" ]; then
  echo "Authentication failed!"
  exit 1
fi

echo "Authenticated successfully!"

# Step 2: Get all companies
echo "Fetching companies..."
COMPANIES=$(curl -s --request GET \
  --url https://api.mydevices.com/v1.0/admin/companies \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json')

echo "Companies:"
echo $COMPANIES | jq '.rows[] | {id: .id, name: .name}'

# Step 3: Get device count for each company
echo "Fetching device counts..."
echo $COMPANIES | jq -r '.rows[] | .id' | while read COMPANY_ID; do
  DEVICE_COUNT=$(curl -s --request GET \
    --url "https://api.mydevices.com/v1.0/admin/things/count?company_id=${COMPANY_ID}" \
    --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' | jq -r '.count')

  echo "Company ${COMPANY_ID}: ${DEVICE_COUNT} devices"
done

This script authenticates, fetches all companies, and counts devices for each - perfect for a billing report!

Query Parameters and Pagination

Most Admin API endpoints support pagination and filtering:

Parameter	Type	Description	Default
page	number	Page number (starts at 0)	0
limit	number	Items per page	50
company_id	number	Filter by company	-
location_id	number	Filter by location	-
user_id	string	Filter by user	-

Example with Pagination

# Get second page with 100 items per page
curl --request GET \
  --url 'https://api.mydevices.com/v1.0/admin/things?page=1&limit=100' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Common Endpoints Quick Reference

Endpoint	Purpose
GET /v1.0/admin/companies	List all companies
GET /v1.0/admin/companies/{id}	Get single company
GET /v1.0/admin/locations	List all locations
GET /v1.0/admin/things	List all devices
GET /v1.0/admin/things/count	Count devices (with filters)
GET /v1.0/admin/users	List all users

For complete endpoint documentation, see the API Reference.

Troubleshooting

401 Unauthorized

Problem: API returns 401 Unauthorized

Solutions:

• Verify your access token is valid and not expired
• Check that you included the Authorization header
• Ensure you're using the correct authentication URL for your realm
• Confirm your Client ID and Client Secret are correct

403 Forbidden

Problem: API returns 403 Forbidden

Solutions:

• Verify your admin API access is enabled in the console
• Check that you're using an admin token (not a user token) for admin routes
• Confirm your account has the necessary permissions

Empty Results

Problem: API returns success but empty results

Solutions:

• Check that you have data in your white label application
• Verify you're querying the correct application_id
• Try removing filters to see if data exists
• Confirm your pagination parameters are correct

Next Steps

Now that you've made your first API calls, explore these resources:

1. Authentication Deep Dive - Learn about admin vs user authentication
2. User-Level Auth - Access user-specific data like device readings
3. API Reference - Complete documentation for all endpoints
4. Resource-Specific Guides:
   • Companies
   • Locations
   • Devices
   • Users

Example Applications

Check out complete example applications on GitHub:

• Python Example
• React Dashboard

Support

Need help? Contact your account manager or support team.