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:
Navigate to Sensos Sync (https://sync.sensos.io) → Settings → API & Integrations. There you will find your tenantId, your active accountId, and the interface to generate M2M client credentials.

Base URL: https://api.sensos.io
Transport: HTTPS (TLS 1.3 / TLS 1.2)
Authentication: OAuth 2.0 / JWT Bearer tokens

Step 1: Generate an Access Token

Sensos utilizes Machine-to-Machine (M2M) application credentials to mint JSON Web Tokens (JWT). Access tokens remain valid for 24 hours (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) for its 24-hour lifetime. Do not request a new token for each API call.

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", []):
    print(f"[{device['id']}] {device['name']} - Status: {device['status']} ({device['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": null
  },
  "devices": [
    {
      "id": "SNS-LBL-001234",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "name": "Warehouse Smart Label #1234",
      "device_type": "SensosLabelGen2",
      "status": "Assigned",
      "connectivityStatus": "Online",
      "configurationStatus": "Applied",
      "cellularProvider": "Atm",
      "activationTime": "2026-09-01T12:00:00Z"
    }
  ]
}

Key Fields Explained

id: Unique identifier (serial / IMEI) of the Sensos Smart Label.
device_type: Hardware type/generation (SensosLabelGen1, SensosLabelGen2).
status: Device operational lifecycle state (Unassigned, Assigned, Paired, Retired).
connectivityStatus: Live network communication and telemetry heartbeat state (Online, Offline, NeverReported).
configurationStatus: Device sensor profile sync status (Applied, Pending).
cellularProvider: Cellular connectivity provider managing the IoT connection (Atm, Vodafone).
nextCursor: Opaque token used for cursor-based pagination. Supply cursor=<nextCursor> in subsequent requests to fetch the next page.

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), and 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, Shipments, Returnable Assets, and Data Delivery with interactive request builders.

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

Getting Started with Sensos API

Architecture & Tenancy Model

Where to find your credentials:

Step 1: Generate an Access Token

Endpoint

Request Code Samples

Expected Response

Best Practice: Cache the `accessToken` in memory or a secure cache (e.g. Redis) for its 24-hour lifetime. Do not request a new token for each API call.

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

Endpoint

Request Code Samples

Step 3: Inspect the Response

Key Fields Explained

Next Steps

Architecture & Tenancy Model

Where to find your credentials:

Step 1: Generate an Access Token

Endpoint

Request Code Samples

Expected Response

Best Practice: Cache the accessToken in memory or a secure cache (e.g. Redis) for its 24-hour lifetime. Do not request a new token for each API call.

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

Endpoint

Request Code Samples

Step 3: Inspect the Response

Key Fields Explained

Next Steps

Best Practice: Cache the `accessToken` in memory or a secure cache (e.g. Redis) for its 24-hour lifetime. Do not request a new token for each API call.