Core Concepts & Roles

This page explains the core concepts and user roles that affect what you can see and do via the REST API.

Understanding this is important before you start calling endpoints like:

• /api/assets

• /api/devices

• /api/plugins/telemetry/...

• /api/alarm/...

Most “why don’t I see X in the API?” questions are answered by:

1. Who owns the entity? (tenant vs customer)

2. What role does my user have? (authority / permissions)

1. Entity Model at a Glance

At a high level, The entities are structured like this:

System
└─ Tenant
   ├─ Customers
   │  ├─ Assets
   │  └─ Devices
   ├─ Assets (tenant-owned)
   ├─ Devices (tenant-owned)
   ├─ Users
   └─ Alarms (attached to assets/devices/other entities)

Key ideas:

• Tenant – logical container for a company/organisation.

• Customer – subgroup inside a tenant (e.g. end client, site, project).

• Assets & Devices – the main entities you will read/write data for.

• Dashboards – visualisations built on top of assets/devices.

• Alarms – events attached to other entities (e.g. generator fault alarm).

2. Main Entities

2.1 Tenant

• Represents a company / organization.

• Owns:

  • Customers

  • Assets

  • Devices

  • Dashboards

  • Users

• Visible & managed primarily by tenant admins and, at a higher level, by system admins.

API impact:

• Tenant admins can typically:

  • Manage all customers

  • See all tenant-owned assets, devices, dashboards

  • Configure device/asset profiles, etc.

2.2 Customer

• Represents a client or logical group inside a tenant.

  • Example: “Customer A”, “Customer B”.

• Used to scope data and permissions:

  • Assets and devices can be assigned to a customer.

  • Customer users can only see entities belonging to their customer.

API impact:

• Endpoints often look like:

  • GET /api/customer/{customerId}

  • GET /api/customer/info/{customerId}

• If you’re logged in as a customer user, customerId is usually your own customer.

2.3 Asset

• Represents logical or physical things that are not strictly “IoT devices”.

  • Examples: building, room, generator, tank, floor, machine group.

• Often used for:

  • Grouping devices

  • Representing locations or sites

  • Acting as a parent entity for alarms, attributes, etc.

  • Saves data from device where applicable.

Common API operations:

• List assets:

  • GET /api/tenant/assets{?assetName} (tenant scope)

  • GET /api/customer/{customerId}/assets{?pageSize,page,type,textSearch,sortProperty,sortOrder} (customer scope)

• CRUD:

  • GET /api/asset/{assetId}

  • POST /api/asset{?entityGroupId,entityGroupIds}

  • DELETE /api/asset/{assetId}

Typically, you will:

1. Find the relevant asset (e.g. “Generator 01”).

2. Find linked devices or telemetry/alarm data for it.

2.4 Device

• Represents a IoT device.

  • Examples: energy meter, temperature sensor, etc.

• Devices send telemetry and hold attributes.

Common API operations:

• List devices:

  • GET /api/tenant/devices{?pageSize,page,type,textSearch,sortProperty,sortOrder}

  • GET /api/customer/{customerId}/devices{?pageSize,page,type,textSearch,sortProperty,sortOrder}

• CRUD:

  • GET /api/device/{deviceId}

  • POST /api/devices

  • DELETE /api/device/{deviceId}

Related concepts:

• Device Profile – defines defaults, transport settings, etc.

• Relationships – Devices can be related to assets (e.g. device belongs to asset “Site 1”).

2.5 Device Profile

• Template/configuration that applies to a group of devices.

  • Example profiles: “Energy Meter”, “Generator Controller”, “Temperature Sensor”.

• Controls:

  • Transport configuration

  • Default attributes

  • Alarm rules (in some setups)

  • Other device-related settings

API impact:

• Some endpoints require a deviceProfileId (e.g. when creating devices).

• Typically managed by tenant admins.

2.6 Asset Profile

• Similar to Device Profile, but for assets.

• Defines:

  • Default settings for a type of asset (e.g. “Site”, “Building”, “Generator”).

  • Optional icons, default attributes, etc.

API impact:

• When creating assets, you can specify the assetProfileId.

• Mostly relevant for tenant admins setting up structure.

2.7 User

• Represents a login identity (username/password) in the system.

• Has:

  • Authority (system-level role, e.g. TENANT_ADMIN, CUSTOMER_USER)

  • Tenant (which tenant they belong to)

  • Customer (for customer users)

API impact:

• A user’s authority and customer determine:

  • Which endpoints they can call.

  • Which entities are visible.

• When a user logs in via /api/auth/login, the JWT token encodes:

  • Their authority

  • Tenant / customer context

2.8 Alarm

• Represents an event or condition attached to another entity:

  • e.g. alarm on a device (“High temperature”)

  • e.g. alarm on an asset (“Generator fault”)

• Can have:

  • Status (active, acknowledged, cleared)

  • Severity

  • Details (JSON with custom fields)

Common API operations:

• POST /api/alarm – create/update an alarm

• GET /api/alarm/{alarmId} – get alarm details

• GET /api/alarm/info/{alarmId} – get alarm info with related entity

• Filtered search (by status, type, originator, etc.)

Alarms are often used as activities, tickets, or alerts in higher-level workflows.

3. Ownership & Access Scope

The structure is multi-tenant and customer-scoped, so every entity has an owner:

• Tenant-owned

  • Visible to that tenant’s admins.

  • Not assigned to a customer.

• Customer-owned (assigned)

  • Assigned to a specific customer within a tenant.

  • Visible to:

    • Tenant admins

    • Users of that customer

3.1 Typical Ownership Patterns

• Assets

  • Can be created as tenant-owned.

  • Can be assigned to a customer.

• Devices

  • Same as assets: can be tenant-owned or assigned to a customer.

3.2 API Scoping

Your API calls are automatically scoped by:

1. Your token (who you are)

   • Tenant admin vs customer user.

2. The IDs you pass

   • e.g. customerId, assetId, deviceId.

Examples:

• A tenant admin can:

  • Call /api/tenant/devices... to see all devices in the tenant.

  • Call /api/customer/{customerId}/devices... to see just one customer’s devices.

• A customer user can:

  • Only see devices/assets assigned to their customer.

  • Cannot see other customers’ entities even if they know the UUID.

4. User Authorities & Roles

Defined authorities (system-level roles) that affect REST API access:

4.1 Built-in Authorities

In our integration docs, we mainly care about CUSTOMER_USER tokens.

4.2 Customer User

Typical use:

• Operators / users linked to a specific customer (e.g. “Customer A’s operations team”).

Can usually do via REST API (depending on permissions configuration):

• Read assets/devices assigned to their customer

• Read telemetry & attributes for those entities

• View dashboards assigned to their customer

• Possibly create alarms or update certain attributes (if allowed)

Cannot do:

• See other customers entities

• Manage tenants or create new customers

• Access tenant-wide configuration endpoints

  
  

5. API Access Patterns by Role

5.1 Customer User Examples

• List “my” devices:

  • GET /api/customer/{myCustomerId}/devices?pageSize=50&page=0

• Read telemetry for devices assigned to my customer.

• View alarms that involve entities belonging to my customer.

If a customer user tries to:

• Access an entity from another customer, or

• Call an admin-only endpoint,

they will receive 403 Forbidden or 404 Not Found, depending on the endpoint and configuration.

6. Common Errors

• 403 vs 404

  • 403 Forbidden – you are authenticated, but not allowed to access this resource.

  • 404 Not Found – entityID does not exist in your scope (or at all).

• Wrong tenant/customer

  • Using IDs from one environment in another (e.g. dev vs prod) will fail.

• Missing assignment

  • Devices/assets created but not assigned to a customer won’t appear for customer users.

• Authority mismatch

  • Using a CUSTOMER_USER token for endpoints that require TENANT_ADMIN will fail.