Examples

The accepted authentication request is:

POST /v1/auth/login HTTP/1.1
Host: api.example.test
Content-Type: application/json

{"identifier":"operator@example.test","password":"<password>"}

Use a cookie-aware client for refresh and never paste the returned access token into shell history.

Numeric Tenant collection and flat member

Tenant selection is explicit for lists and creates:

GET /v1/tenants/17/devices?limit=50 HTTP/1.1
Authorization: Bearer <access-token>

The response reports the exact filtered count independently of the current page size:

{
  "items": [],
  "totalCount": 0
}

nextCursor is present only when another page exists. limit defaults to 25 and accepts only 25, 50, or 100.

An existing Device is addressed only by its globally unique aggregate ID:

GET /v1/devices/{deviceId} HTTP/1.1
PATCH /v1/devices/{deviceId} HTTP/1.1
GET /v1/devices/{deviceId}/measurements?from=2026-08-09T00%3A00%3A00Z&to=2026-08-10T00%3A00%3A00Z HTTP/1.1

The same rule applies to the other Tenant-owned aggregates:

GET|POST /v1/tenants/17/device-types
GET|PATCH /v1/device-types/{deviceTypeId}
GET       /v1/device-types/{deviceTypeId}/fields

GET|POST /v1/tenants/17/memberships
GET|PATCH|DELETE /v1/memberships/{membershipId}

GET|POST /v1/tenants/17/organization-units
GET       /v1/tenants/17/organization-units/roots?limit=50
GET|PATCH|DELETE /v1/organization-units/{organizationUnitId}
GET       /v1/organization-units/{organizationUnitId}/children?limit=50
GET       /v1/tenants/17/organization-units/search?q=vienna&limit=50

GET       /v1/tenants/17/flows
POST      /v1/device-types/{deviceTypeId}/flow
GET|POST  /v1/flows/{flowId}/versions
POST      /v1/flows/{flowId}/versions/{flowVersionId}/validate

Tenant responses contain both identifiers:

{
  "tenantId": "10000000-0000-4000-8000-000000000001",
  "tenantNumber": 17,
  "key": "north-factory",
  "name": "North Factory"
}

The UUID remains the internal security and data-isolation identifier. The number is a public locator and does not grant access.

Large telemetry downloads should use export jobs instead of synchronous API queries.