Getting Started with Sensos API

The Sensos REST API connects your enterprise systems (TMS, ERP, WMS, and supply chain control towers) directly to Sensos AIoT Smart Labels and the cloud analytics engine for real-time, end-to-end supply chain visibility.

Follow this 5-minute quickstart to authenticate, issue your first API call, and inspect live device telemetry.

Architecture & Tenancy Model

Before making API calls, it is important to understand the Sensos organizational hierarchy:

Tenant (tenantId): Represents your enterprise organization within Sensos. Your M2M application credentials (applicationId and applicationSecret) are provisioned at the tenant level.
Account (accountId): Represents an operational workspace, business unit, or regional division within your tenant. All operational resources—shipments, devices, and data delivery rules—are scoped to an accountId.

💡
Where to find your credentials:
In Sensos Sync (https://sync.sensos.io), go to Admin → Users & Apps → Applications and create an M2M application. The dialog shows its applicationId, your tenantId and the applicationSecret. Copy the secret right away: it is shown only once. Your accountId is the ID after /accounts/ in the Sync URL.

Base URL: https://api.sensos.io
Transport: HTTPS (TLS 1.3 / TLS 1.2)
Authentication: JWT Bearer tokens issued for your application credentials

Step 1: Generate an Access Token

Sensos utilizes Machine-to-Machine (M2M) application credentials to mint JSON Web Tokens (JWT). The token response tells you how long the token remains valid in expiresIn (seconds). The same token is reused for up to 12 hours, so expiresIn is between about 43,200 and 86,400 seconds.

Endpoint

POST https://api.sensos.io/v1/applications/token
Content-Type: application/json

Request Code Samples

curl -X POST "https://api.sensos.io/v1/applications/token" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "YOUR_TENANT_ID",
    "applicationId": "YOUR_APPLICATION_ID",
    "applicationSecret": "YOUR_APPLICATION_SECRET"
  }'

import requests

url = "https://api.sensos.io/v1/applications/token"
payload = {
    "tenantId": "YOUR_TENANT_ID",
    "applicationId": "YOUR_APPLICATION_ID",
    "applicationSecret": "YOUR_APPLICATION_SECRET"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()

data = response.json()
access_token = data["accessToken"]
print(f"Token acquired. Expires in: {data['expiresIn']} seconds")

interface TokenResponse {
  accessToken: string;
  expiresIn: number;
}

async function getAccessToken(): Promise<string> {
  const response = await fetch("https://api.sensos.io/v1/applications/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      tenantId: "YOUR_TENANT_ID",
      applicationId: "YOUR_APPLICATION_ID",
      applicationSecret: "YOUR_APPLICATION_SECRET"
    })
  });

  if (!response.ok) {
    throw new Error(`Authentication failed: ${response.status} ${response.statusText}`);
  }

  const data = (await response.json()) as TokenResponse;
  return data.accessToken;
}

using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var client = new HttpClient();
var payload = new
{
    tenantId = "YOUR_TENANT_ID",
    applicationId = "YOUR_APPLICATION_ID",
    applicationSecret = "YOUR_APPLICATION_SECRET"
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.sensos.io/v1/applications/token", content);
response.EnsureSuccessStatusCode();

var responseJson = await response.Content.ReadAsStringAsync();
using var doc = JsonDocument.Parse(responseJson);
string accessToken = doc.RootElement.GetProperty("accessToken").GetString();

Expected Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

🛡️
Best Practice: Cache the accessToken in memory or a secure cache (e.g. Redis) and request a new one shortly before expiresIn seconds have passed. Do not request a new token for each API call. Token expiry is checked with a 5-minute clock-skew tolerance, so keep your servers' clocks synchronized (e.g. NTP).

Step 2: Make Your First API Call (List Devices)

Once authenticated, supply the access token in the Authorization: Bearer <token> header on all requests.

Every provisioned Sensos account contains devices (Sensos Smart Labels). Let's retrieve the first 10 devices registered under your operational account.

Endpoint

GET https://api.sensos.io/v1/accounts/{accountId}/devices?limit=10&includeTotal=true
Authorization: Bearer <accessToken>
Accept: application/json

Request Code Samples

curl -X GET "https://api.sensos.io/v1/accounts/YOUR_ACCOUNT_ID/devices?limit=10&includeTotal=true" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Accept: application/json"

import requests

account_id = "YOUR_ACCOUNT_ID"
url = f"https://api.sensos.io/v1/accounts/{account_id}/devices"
params = {"limit": 10, "includeTotal": "true"}
headers = {
    "Authorization": f"Bearer {access_token}",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()

data = response.json()
for device in data.get("devices", []):
    # status and connectivityStatus are not returned for BLE tags
    print(f"[{device['id']}] {device.get('name')} - Status: {device.get('status')} ({device.get('connectivityStatus')})")

async function listDevices(accountId: string, token: string) {
  const url = `https://api.sensos.io/v1/accounts/${accountId}/devices?limit=10&includeTotal=true`;
  const response = await fetch(url, {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Accept": "application/json"
    }
  });

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
  }

  const result = await response.json();
  console.log(`Retrieved ${result.devices.length} devices.`);
  return result;
}

using System.Net.Http.Headers;

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var getResponse = await client.GetAsync($"https://api.sensos.io/v1/accounts/{accountId}/devices?limit=10&includeTotal=true");
getResponse.EnsureSuccessStatusCode();

string resultJson = await getResponse.Content.ReadAsStringAsync();
Console.WriteLine(resultJson);

Step 3: Inspect the Response

{
  "metadata": {
    "total": 1,
    "nextCursor": ""
  },
  "devices": [
    {
      "id": "SNS-LBL-001234",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "name": "Warehouse Smart Label #1234",
      "deviceType": "SensosLabelGen2",
      "status": "Assigned",
      "connectivityStatus": "Online",
      "configurationStatus": "Applied",
      "cellularProvider": "Atnt",
      "activationTime": "2026-09-01T12:00:00Z"
    }
  ]
}

Key Fields Explained

id: Unique identifier (serial / IMEI) of the Sensos Smart Label.
deviceType: Hardware type/generation (SensosLabelGen1, SensosLabelGen2, BleTag).
status: Device operational lifecycle state (Unassigned, Assigned, Retired). Not returned for BLE tags.
connectivityStatus: Live network communication and telemetry heartbeat state (Online, Offline, NeverReported). Not returned for BLE tags.
configurationStatus: Device sensor profile sync status (Pending, Applied, Failed).
cellularProvider: Cellular connectivity provider managing the IoT connection (Atnt, Vodafone, Truphone, Monogoto, None).
nextCursor: Opaque token used for cursor-based pagination. Supply cursor=<nextCursor> in subsequent requests to fetch the next page. It is an empty string ("") on the last page. See Pagination.

Next Steps

Now that you have completed authentication and made your first request, explore the following developer resources:

Authentication & Token Caching – Learn production best practices for token lifecycle management, error handling (401 Unauthorized), secret rotation, and the 5-minute clock-skew tolerance.
Data Delivery & Webhooks – Configure automated HTTPS webhooks to stream sensor measurements and threshold-breach alerts to your infrastructure.
Interactive API Reference – Explore all available endpoints across Devices, Tracking (Shipments, Assets), Configuration (Sets, Items, Points of Interest, Carriers), Data Delivery, and Authentication with interactive request builders.

Developer Support – Have questions or need enterprise integration assistance? Reach out to our engineering team at [email protected].

Architecture & Tenancy Model

Where to find your credentials:

Step 1: Generate an Access Token

Endpoint

Request Code Samples

Expected Response

Step 2: Make Your First API Call (List Devices)

Endpoint

Request Code Samples

Step 3: Inspect the Response

Key Fields Explained

Next Steps