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 shipment 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, smart labels, environmental monitoring plans, and data delivery rules—are scoped to an accountId.

💡
Where to find your credentials:
Navigate to Sensos Sync (https://app.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

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

Python (requests)

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

Node.js / TypeScript (fetch)

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

C# / .NET (HttpClient)

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 Shipments)

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

Let's retrieve the first 10 shipments registered under your operational account.

Endpoint

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

Request Code Samples

cURL

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

Python (requests)

import requests

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

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

shipments = response.json()
for shipment in shipments.get("items", []):
    print(f"[{shipment['id']}] {shipment['name']} - Status: {shipment['status']}")

Node.js / TypeScript (fetch)

async function listShipments(accountId: string, token: string) {
  const url = `https://api.sensos.io/v1/accounts/${accountId}/shipments?limit=10`;
  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.items.length} shipments.`);
  return result;
}

C# / .NET (HttpClient)

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}/shipments?limit=10");
getResponse.EnsureSuccessStatusCode();

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

Step 3: Inspect the Response

{
  "items": [
    {
      "id": "shp_98a42e1b",
      "name": "Cold-Chain Pharma Batch #1048",
      "status": "InTransit",
      "origin": {
        "id": "poi_38a201",
        "name": "Frankfurt Central Distribution Center",
        "coordinates": {
          "latitude": 50.1109,
          "longitude": 8.6821
        }
      },
      "destination": {
        "id": "poi_99f412",
        "name": "Chicago Medical Hub",
        "coordinates": {
          "latitude": 41.8781,
          "longitude": -87.6298
        }
      },
      "carrier": {
        "carrierId": "car_lufthansa_cargo",
        "name": "Lufthansa Cargo"
      },
      "labels": [
        "lbl_00284719"
      ],
      "planId": "pln_pharma_cold_chain_v2",
      "createdAt": "2026-09-14T08:30:00Z",
      "updatedAt": "2026-09-15T10:15:00Z"
    }
  ],
  "metadata": {
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA5LTE0VDA4OjMwOjAwWiIsImlkIjoic2hwXzk4YTQyZTFiIn0=",
    "total": 1
  }
}

Key Fields Explained

status: Current shipment state (Draft, Scheduled, InTransit, Delivered, Archived).
labels: Array of attached Sensos Smart Labels. Smart Labels automatically transmit environmental telemetry (temperature, humidity, shock, ambient light) and cellular location pings back to Sensos cloud.
planId: The active environmental monitoring plan evaluating temperature bounds, shock thresholds, and dwell times.
origin & destination: Geofenced Points of Interest (POIs) that trigger automatic departure and arrival milestone events.
nextCursor: Opaque token used for cursor-based pagination. Supply cursor=<nextCursor> in your subsequent request to fetch the next page.

Next Steps

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

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 Shipments, Devices, Smart Labels, Monitoring Plans, Attachments, and Returnable Assets 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

cURL

Python (requests)

Node.js / TypeScript (fetch)

C# / .NET (HttpClient)

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 Shipments)

Endpoint

Request Code Samples

cURL

Python (requests)

Node.js / TypeScript (fetch)

C# / .NET (HttpClient)

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

cURL

Python (requests)

Node.js / TypeScript (fetch)

C# / .NET (HttpClient)

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 Shipments)

Endpoint

Request Code Samples

cURL

Python (requests)

Node.js / TypeScript (fetch)

C# / .NET (HttpClient)

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.