REST API Integration

Thingsboard API Overview

Welcome to the internal documentation for our REST APIs.
This section explains how to call our REST endpoints, how authentication works, and what different users are allowed to do.
This part of the wiki explains how to use our instance via REST APIs
The detailed swagger APIs can be found at this LINK

What this section is for

Use this wiki when you need to:

  • Integrate an internal service with us (e.g. microservices, backend jobs).

  • Build scripts or tools that read/write data.

  • Troubleshoot API permissions, missing data, or error responses.

  • Understand how our company uses entities and endpoints (assets, devices, telemetry, alarms, etc.).

Scope & Assumptions

  • Protocol: Only REST APIs are covered here.

  • Audience: Internal developers and power users with access to our instance.

  • Access: We assume you already have a user account or device credentials.

If you are completely new start with:

When to use the REST APIs

Typical use cases:

  • Backend integrations

    • Sync assets/devices with another system (CRM, ERP, CMMS, etc.).

    • Automatically create devices/assets for new customers.

  • Data access

    • Fetch telemetry attributes.

  • System management

    • Manage customers, assets, devices, dashboards.

    • Create and manage alarms (e.g. activities, alerts).

High-Level REST API Map

At a very high level, we use the REST API for:

  1. Authentication

    • /api/auth/login → Get a JWT token for a user.

    • X-Authorization: Bearer <token> header on all calls.

  2. Entity Management

    • Tenants & Customers (tenant admins only)

    • Assets (sites, locations, equipment, etc.)

    • Devices (sensors, gateways, controllers)

  3. Telemetry & Attributes

    • Read historical telemetry

    • Read/write attributes (client, shared, server)

  4. Alarms

    • Create, list, acknowledge, and clear alarms.

The detailed endpoints and examples are documented on the subpages listed below.

Permissions & Access (Who can see what?)

Roles/authorities (e.g. TENANT_ADMIN, CUSTOMER_USER) and entity ownership (tenant → customer → assets/devices).

Your user’s role and customer determine:

  • Which endpoints you are allowed to call.

  • Which entities you can see or modify.

  • Whether an API returns data, 403 (forbidden), or 404 (not found).

Details are in:
Core Concepts & Roles

Quick Start: Common Flows

These are the three most common things people do with the REST API:

  1. Log in and get a JWT token

    • Call /api/auth/login with your username/password.

    • Use the returned token in X-Authorization: Bearer <token>.

  2. List my assets or devices

    • Call “list” endpoints with your token.

    • The result set is filtered automatically by your permissions.

  3. Read telemetry for a device

    • Use the telemetry endpoints to get latest values or history.

    • Pass the device ID, keys, and time range.

Each flow is documented step-by-step with request/response examples in: