Developer Guide

REST API Overview

The IoTRoutes REST API exposes all core platform functionalities for external systems, integrations, and automation scripts.
Through the API, developers can manage devices, send commands, query the attribute ledger, handle workflows, and interact with stored files.

The API follows RESTful conventions, uses JSON as the data format, and requires JWT-based authentication for every request.

1. API EndPoints 

All platform API endpoints are exposed under the base path https://<your-AOS-url>/<your-subscription>/api/ .

For example  on the cloud version  https://aos.iotroutes.com/<your-subscription>/api/.

 Full API documentation is available through Swagger at https://<your-AOS-url>/swagger/index.html. 

API documentation is also accessible from the web client under Platform Administration → Server API, where an embedded Swagger UI allows users to test API calls directly. 

When this embedded Swagger is opened, the platform automatically retrieves the current user’s bearer token; the user can simply paste it into the Authorize dialog to authenticate Swagger requests, making it possible to execute API calls with the permissions of the currently logged-in user.

 

2. Authentication

IoTRoutes uses Bearer tokens (JWT) for authentication and authorization.
Tokens are issued when a user logs in via the platform or through the /api/auth endpoint.

Login request example:
POST /api/auth Content-Type: application/json {  "username": "admin",  "password": "yourpassword" }
Successful response:
{
  "tokenId": "eyJhb22NjE4OCwiaWF0IjoxNzYzMDYyNTg4fQ.....",
  "expiresOn": "2025-11-13T20:36:28.0984148Z",
  "refreshToken": "qq839aa-804b-4071-8263-bqqccdac13",
  "refreshExpiresOn": "2025-11-13T20:51:28.1025297Z",
  "user": {
    "userName": "myname",
    "email": "mymail@mydomain.com",
    "name": "administrator",
    "lastName": "-",
    "mustLogout": false,
    "mustChangePwd": false,
    "roles": [
      "SysAdmin"
    ],
    "internalEntities": [],
    "customerEntityId": null,
    "preferences": [
      {
        "name": "Culture",
        "value": "en"
      }
    ]
  }
}

The token must then be included in the Authorization header of every subsequent API call: Authorization: Bearer <tokenid> 

Access to each API route also depends on the permissions assigned to the current user’s role. Every API controller and action maps to a system Object, and authorization is enforced based on the rights configured under System Administration → Roles. For example, a role must have at least View permission on the Devices object to execute GET api/Devices. Without the appropriate rights, the API call will be rejected even if the bearer token is valid.
 

3. API Conventions

ElementDescription
FormatJSON request and response payloads.
NamingResource-oriented URLs (e.g., /devices,/attributes , /messages).
PaginationSupported via page, size , filter and sort queryOptions parameter.
TimestampsISO 8601 format (UTC).
ErrorsReturned with standard HTTP codes and JSON error details.
Example error response
{  "error": "Unauthorized",  "message": "Invalid or expired token." } 
 
 
Common structures
IoTRoutes APIs follow a set of common structural conventions across almost all endpoint groups. Each API exposes a List route (/List) that supports pagination and filtering using a QueryOptions request body, allowing clients to apply sorting, filtering rules, page size, and other domain-specific options. A complementary Lookup route returns lightweight records in DataLookup format, containing only the entity ID and a small set of key/value display fields, optimized for dropdowns, selectors, and autocomplete components. Standard CRUD operations are also aligned across APIs, including POST to create new records, PATCH using a DataPatch object to update specific fields of a record by Id, PUT for full entity updates, and DELETE to remove a record. In addition to these shared conventions, each API can define additional functional routes specific to the domain it manages (devices, workflows, attributes, commands, etc.), following the same overall naming and structural principles.
 
QueryOptions structure
{
  "filters": [
    {
      "fieldName": "string",
      "operator": "Equal",
      "value": "string",
      "isOr": true
    }
  ],
  "sortByField": "string",
  "sortByDesc": true,
  "skip": 0,
  "take": 0,
  "getTotalCount": true
}
 

4. API Access Limits

ll IoTRoutes APIs are protected by an internal gateway middleware that enforces rate limiting to ensure platform stability and prevent abusive or accidental overload of backend services. Rate-limit rules are fully configurable through the ApiRateLimit  section in the application settings. This configuration allows enabling or disabling rate control, defining a global limit per minute, specifying optional per-route overrides (for example /api/auth, /api/definition/*, or /api/FileStore).

A special  ByPass_Key header value to exempt trusted internal processes or automation tools from rate limits. A typical configuration block looks like this:

"ApiRateLimit": {
  "Enabled": true,
  "ByPass_Key": "THIS_KEY_BYPASS_GATEWAY(Header:ByPass_Key)",
  "DefaultPerMinute": 60,
  "PerRoute": {
    "/api/auth": 10,
    "/api/definition/*": 30,
    "/api/FileStore": 30
  }
}
 

 Best Practices

  • Use tokens securely — never expose them in client-side code or logs.

  • Use pagination for all list endpoints to optimize performance.

  • Leverage filters (status, class, dateFrom, dateTo) for analytics queries.

  • Combine APIs and Workflows — trigger or extend workflows directly from external systems using HTTP requests.

  • Monitor API limits — large installations may enforce rate limits per user or token.

  • Test on sandbox — use a test environment before deploying integrations to production.

Stay connected

All you need is an internet connection.
OSPO

Contact

LiM Products

  • Procurement
  • Sales & Marketing
  • Inventory
  • Retail
  • HR & Payroll
  • Tax Declaration
  • Accountig

IoT

  • IoT Platforms
  • IoT Services
  • IoT Devices

IoT Routes
© 2025 Copyrights by OSPO. All Rights Reserved

Recent Posts