SOT Learning Portal

Concepts

Tenants

Every customer or organization works in its own tenant. The data of every tenant are stored separately.

  • Every API path contains the tenant: …/tenants/{tenantId}/….

  • The tenant of the access token must match {tenantId}. Otherwise the request is rejected with 403.

Authentication

All APIs and MCP servers require an OAuth 2.0 access token (JWT) in the Authorization header:

Authorization: Bearer <access token>

The tokens are issued by the identity provider (Keycloak) of your tenant. Every tenant has its own realm.

Technical clients

Machines, connectors and other applications use a technical client with the client credentials flow. Your administrator provides:

Request a token:

curl -X POST "https://<identity-host>/auth/realms/<realm>/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id=<client-id> \
  -d client_secret=<client-secret>

The response contains access_token and expires_in (seconds). Reuse the token until shortly before it expires, then request a new one.

Keep the client secret secret. Do not store it in source code. Use a separate client for every machine or application, so that you can revoke it individually.

Users

In the browser, users log in through the Smart Operations Toolkit. The tokens are kept in secure cookies; the browser application never handles tokens. See Login in the browser.

Permissions

Every operation requires a permission (role) in the token, for example devices:read to see devices or rules:write to create rules. The required permission is listed for every endpoint and MCP tool. Users see their permissions in their profile.

The agent acts on behalf of the user. It can only do what the user is permitted to do.

Area Permissions

Devices, device types, measuring points, facilities

devices:*, device_types:*, measuring_points:*, facilities:*

Measured values and events

measurements:read, events:read

Rules

rules:read, rules:write, rules:delete

Processes

processes:read, processes:export

Email templates

templates:read, templates:write, templates:delete

Agent chat

ai_chat:read

Sending machine data

measurements:write (technical clients)

* stands for read, write and delete.

Base URLs

All APIs are reached under the same host. The path prefix depends on the function:

Function REST API MCP server

Machine data

/data-ingest/api/v1/tenants/{tenantId}

–

Master data

/mdm/api/v1/tenants/{tenantId}

/mdm/tenants/{tenantId}/mcp

Measured values, events and rules

/cm/api/v1/tenants/{tenantId}

/cm/api/v1/tenants/{tenantId}/mcp

Process data

/pqm/api/v1/tenants/{tenantId}

/pqm/tenants/{tenantId}/mcp

Email notifications

/nfs/api/v1/tenants/{tenantId}

/nfs/tenants/{tenantId}/mcp

User settings

/portal/api/v1/tenants/{tenantId}

/portal/tenants/{tenantId}/mcp

API conventions

  • Requests and responses use JSON (application/json).

  • Timestamps are in UTC in RFC 3339 / ISO 8601 format, for example 2026-10-16T10:00:00Z.

  • Devices, device types, measuring points and facilities are identified by UUIDs. Machines identify a device by its technical ID. APIs that work with a device, for example measured values or processes, expect the UUID; look it up with the master data API by the technical ID.

  • Lists are paged. Master data and rules use page and pageSize (at most 100). Measured values and events use cursor and asOf to continue with the next page.

  • Errors are returned as JSON with a machine-readable code and a human-readable message. Include the traceId, if present, when you contact support.

  • 401 means that the token is missing or invalid. 403 means that a permission is missing or the tenant does not match.

Konzepte

Tenants

Jeder Kunde und jede Organisation arbeitet in einem eigenen Tenant. Die Daten jedes Tenants werden getrennt gespeichert.

  • Jeder API-Pfad enthält den Tenant: …/tenants/{tenantId}/….

  • Der Tenant des Zugriffstokens muss mit {tenantId} übereinstimmen. Andernfalls lehnt die API die Anfrage mit 403 ab.

Authentifizierung

Alle APIs und MCP-Server erfordern ein OAuth-2.0-Zugriffstoken (JWT) im Header Authorization:

Authorization: Bearer <access token>

Die Tokens stellt der Identity Provider (Keycloak) des Tenants aus. Jeder Tenant hat einen eigenen Realm.

Technische Clients

Maschinen, Konnektoren und andere Anwendungen verwenden einen technischen Client mit dem Client-Credentials-Flow. Der Administrator stellt bereit:

Token anfordern:

curl -X POST "https://<identity-host>/auth/realms/<realm>/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id=<client-id> \
  -d client_secret=<client-secret>

Die Antwort enthält access_token und expires_in (Sekunden). Das Token bis kurz vor Ablauf wiederverwenden, dann ein neues anfordern.

Das Client-Secret geheim halten und nicht im Quellcode speichern. Für jede Maschine und jede Anwendung einen eigenen Client verwenden, damit sich jeder Client einzeln widerrufen lässt.

Benutzer

Im Browser melden sich Benutzer über das Smart Operations Toolkit an. Die Tokens liegen in sicheren Cookies; die Browseranwendung verarbeitet nie Tokens. Siehe Anmeldung im Browser.

Berechtigungen

Jede Operation erfordert eine Berechtigung (Rolle) im Token, zum Beispiel devices:read zum Anzeigen von Geräten oder rules:write zum Anlegen von Regeln. Die erforderliche Berechtigung ist bei jedem Endpunkt und jedem MCP-Tool angegeben. Benutzer sehen ihre Berechtigungen im Profil.

Der Agent handelt im Auftrag des Benutzers. Er kann nur ausführen, wozu der Benutzer berechtigt ist.

Bereich Berechtigungen

Geräte, Gerätetypen, Messpunkte, Anlagen

devices:*, device_types:*, measuring_points:*, facilities:*

Messwerte und Ereignisse

measurements:read, events:read

Regeln

rules:read, rules:write, rules:delete

Prozesse

processes:read, processes:export

E-Mail-Vorlagen

templates:read, templates:write, templates:delete

Agent-Chat

ai_chat:read

Senden von Maschinendaten

measurements:write (technische Clients)

* steht für read, write und delete.

Basis-URLs

Alle APIs sind unter demselben Host erreichbar. Das Pfadpräfix hängt von der Funktion ab:

Funktion REST-API MCP-Server

Maschinendaten

/data-ingest/api/v1/tenants/{tenantId}

–

Stammdaten

/mdm/api/v1/tenants/{tenantId}

/mdm/tenants/{tenantId}/mcp

Messwerte, Ereignisse und Regeln

/cm/api/v1/tenants/{tenantId}

/cm/api/v1/tenants/{tenantId}/mcp

Prozessdaten

/pqm/api/v1/tenants/{tenantId}

/pqm/tenants/{tenantId}/mcp

E-Mail-Benachrichtigungen

/nfs/api/v1/tenants/{tenantId}

/nfs/tenants/{tenantId}/mcp

Benutzereinstellungen

/portal/api/v1/tenants/{tenantId}

/portal/tenants/{tenantId}/mcp

API-Konventionen

  • Anfragen und Antworten verwenden JSON (application/json).

  • Zeitstempel stehen in UTC im Format RFC 3339 / ISO 8601, zum Beispiel 2026-10-16T10:00:00Z.

  • Geräte, Gerätetypen, Messpunkte und Anlagen werden über UUIDs identifiziert. Maschinen identifizieren ein Gerät über seine technische ID. APIs, die mit einem Gerät arbeiten, zum Beispiel für Messwerte oder Prozesse, erwarten die UUID. Die UUID lässt sich mit der Stammdaten-API über die technische ID ermitteln.

  • Listen sind in Seiten aufgeteilt. Stammdaten und Regeln verwenden page und pageSize (höchstens 100). Messwerte und Ereignisse verwenden cursor und asOf, um mit der nächsten Seite fortzufahren.

  • Fehler kommen als JSON mit einem maschinenlesbaren code und einer lesbaren Meldung zurück. Bei Anfragen an den Support die traceId angeben, falls vorhanden.

  • 401 bedeutet, dass das Token fehlt oder ungültig ist. 403 bedeutet, dass eine Berechtigung fehlt oder der Tenant nicht übereinstimmt.

Diese Seite bearbeiten Edit this page

Feedback on this pageFeedback zu dieser Seite