API-Tokens

Mit API-Tokens verbinden Sie externe Systeme, Skripte und Tools mit der Mirox-Plattform über scoped, widerrufbare Anmeldedaten, die niemals Ihr Passwort preisgeben. Jeder Token authentifiziert Machine-to-Machine-Anfragen in Ihrem Namen, sodass Sie Metriken exportieren und Ihre Integrationen automatisieren können, ohne Ihr Login zu teilen.

Token-Konzept

Jeder Token gehört dem Benutzer, der ihn erstellt hat, und verhält sich wie dieser Benutzer, innerhalb gewisser Grenzen:

An Ihr Konto gebunden — ein Token handelt in Ihrem Namen, und alles, was er tut, wird Ihnen im Audit-Trail zugeordnet.
Berechtigungsobergrenze — ein Token kann niemals auf etwas zugreifen, auf das Sie selbst keinen Zugriff haben. Ihre eigene Rolle und Ihr Ressourcenzugriff begrenzen stets, was der Token sieht.
Durch Berechtigungsgruppe scoped — Sie wählen bei der Erstellung eine Berechtigungsgruppe, um den Token weiter einzuschränken (siehe unten).
Einmalig angezeigt — der vollständige Token-Wert wird bei der Erstellung ein einziges Mal angezeigt. Bewahren Sie ihn sicher auf; Mirox speichert nur eine gehashte Kopie und kann ihn niemals wieder anzeigen.
Für die Automatisierung gemacht — ein Token wird nie nach einem zweiten Faktor gefragt, und die Anmelderegeln Ihrer Organisation beenden ihn nicht. Siehe Tokens und Zwei-Faktor-Authentifizierung.

So bleibt Automatisierung nachvollziehbar: Selbst wenn ein Token kompromittiert wird, ist er auf einen Scope beschränkt, leicht zu widerrufen und von Ihren anderen Tokens isoliert.

Berechtigungsgruppen

Wenn Sie einen Token erstellen, wählen Sie eine Berechtigungsgruppe, die definiert, was er tun darf:

Gruppe	Was der Token tun kann
Full Access	Handelt mit Ihrem vollständigen Zugriff — jede API-Oberfläche, die Sie erreichen können.
Metric Export	Nur den Datenexport lesen: Metriken als Zeitreihe, Exportvorlagen, den Metrikkatalog, Anlageninformationen und Ereignisse. Er kann nichts ändern.
Timeseries Database	Nur die rohen Messreihen lesen.

Eine Gruppe erweitert niemals Ihren Zugriff; sie schränkt den Token lediglich relativ zu Ihren eigenen Berechtigungen ein. Die vollständige Definition jeder Gruppe finden Sie im Abschnitt API-Berechtigungsgruppen der Dokumentation zum Berechtigungssystem.

Gruppe an die Aufgabe anpassen

Geben Sie jeder Integration die engste Gruppe, die noch funktioniert. Eine Arbeitsmappe oder ein Skript, das Exporte liest, benötigt nur Metric Export; ein Client, der die rohen Messreihen liest, benötigt nur Timeseries Database. Das begrenzt den Schadensradius, falls ein Token nach außen gelangt.

Tokens erstellen und verwalten

Sie verwalten Ihre Tokens in Ihrem Profil. Die Plattform deckt den gesamten Lebenszyklus ab:

Einen Token erstellen

Name und Beschreibung — eine eindeutige Bezeichnung und ein Hinweis, damit Sie sich erinnern, wofür jeder Token gedacht ist.
Berechtigungsgruppe — wählen Sie eine der oben genannten Gruppen.
Ablauf — optional. Tokens haben standardmäßig eine Laufzeit von einem Jahr, und Sie können einen beliebigen Ablauf bis zu maximal fünf Jahren festlegen.
Einmalige Anzeige — der vollständige Token wird bei der Erstellung einmal angezeigt und danach nie wieder.

Sie können bis zu 64 aktive Tokens pro Konto halten.

Erstellen und Rotieren im Browser

Sie erstellen und rotieren Tokens im Browser, während Sie bei Mirox angemeldet sind. Sie können nicht einen API-Token verwenden, um einen anderen zu erstellen oder zu rotieren — das verhindert, dass ein nach außen gelangter Token unbemerkt weitere erzeugt.

Einen Token rotieren

Die Rotation ersetzt das Geheimnis eines Tokens an Ort und Stelle, ohne dessen Name, Beschreibung oder Berechtigungsgruppe zu ändern:

Ein neues Geheimnis wird ausgestellt und einmal angezeigt.
Das alte Geheimnis funktioniert sofort nicht mehr.
Der Ablauf wird zurückgesetzt und der Nutzungsverlauf gelöscht.

Die Rotation ist der empfohlene Weg, um langlebige Integrationen planmäßig zu erneuern oder auf einen vermuteten Leak zu reagieren, ohne neu konfigurieren zu müssen, welche Integration welchen Token verwendet.

Überwachen und Widerrufen

Bestand — listen Sie alle Ihre Tokens mit Name, Berechtigungsgruppe sowie Erstellungs- und Ablaufdatum auf.
Nutzungseinblick — sehen Sie, wann jeder Token zuletzt verwendet wurde, zusammen mit der IP, dem Standort, dem Browser und dem Betriebssystem, die zu diesem Zeitpunkt erfasst wurden. Der Token-Wert selbst wird niemals erneut angezeigt.
Sofortiger Widerruf — löschen Sie einen Token, um ihn umgehend ungültig zu machen. Das Widerrufen eines Tokens betrifft niemals die anderen.

Tokens und Zwei-Faktor-Authentifizierung

Ein API-Token ist für Skripte und Integrationen gemacht, die ohne einen Menschen an der Tastatur laufen. Die Anmelderegeln für Personen gelten deshalb nicht für ihn:

Kein zweiter Faktor. Ein Token wird nie nach einem Code gefragt, egal ob Ihr Konto Zwei-Faktor-Authentifizierung (2FA) hat oder nicht.
Nicht durch Anmelderegeln beendet. Ihre Organisation kann festlegen, wie lange eine Anmeldung an der Web-App und an der Mobile App gilt. Ein Token ist keine Anmeldung: Er funktioniert bis zu seinem eigenen Ablaufdatum oder bis Sie ihn rotieren oder widerrufen. Eine Abmeldung stoppt Ihre Tokens nicht.
Nicht durch eine 2FA-Pflicht verändert. Wenn eine Organisation 2FA für den Zugriff auf Anlagen verlangt, gilt diese Regel für Personen, die an der Web-App und an der Mobile App angemeldet sind. Sie ändert nicht, was ein bestehender Token erreichen kann.

Eine Regel gilt doch: Solange Ihre eigene Organisation 2FA verlangt und Ihr Konto keinen zweiten Faktor hat, können Sie keinen neuen Token erstellen. Aktivieren Sie zuerst 2FA (Authenticator-App oder Passkey) — siehe Zwei-Faktor-Authentifizierung. Ihre bestehenden Tokens funktionieren in der Zwischenzeit weiter.

Weil ein Token nicht durch einen zweiten Faktor geschützt ist, behandeln Sie ihn wie ein Passwort: Bewahren Sie ihn sicher auf, geben Sie ihm die engste Berechtigungsgruppe, setzen Sie ein Ablaufdatum und widerrufen Sie ihn, wenn er nicht mehr gebraucht wird. Die Regeln der Organisation stehen unter Sicherheitsrichtlinie der Organisation.

Häufige Anwendungsfälle

API-Tokens unterstützen eine breite Palette von Integrationsszenarien.

Metric Export

Ein Token Metric Export liest jeden Link des Metric Export und des Legacy-Exports:

Aktualisieren Sie Excel-Arbeitsmappen und BI-Dashboards aus einem Export-Link.
Speisen Sie Produktions- und Leistungsdaten in Data Warehouses und Analyse-Pipelines ein.
Erstellen Sie eigene Berichte aus exportierten Daten.

Das Token kann weder Vorlagen noch Metriken noch sonst etwas erstellen oder ändern. Die Berichte, die Mirox selbst erstellt, werden nicht über API-Tokens gesteuert: Sie werden in der App erstellt, veröffentlicht und heruntergeladen.

Zugriff auf Zeitreihen-Metriken

Lesen Sie die rohen Messreihen Ihrer Anlagen, dieselben Reihen, die Grafana liest.
Verbinden Sie schreibgeschützte Analyse-Tools, die die Abfragesprache des Zeitreihenspeichers sprechen.

Sicherheit und Kontrolle

Token-Isolation — ein kompromittierter Token gibt niemals Ihr Passwort oder Ihre anderen Tokens preis.
Geplante Rotation — rotieren Sie langlebige Tokens regelmäßig über die Rotate-Aktion und behalten Sie dabei dieselbe Konfiguration.
Zeitlich begrenzte Gültigkeit — legen Sie einen Ablauf fest, damit aufgegebene Tokens automatisch verfallen.
Vollständige Zuordnung — jede Aktion, die ein Token ausführt, wird Ihnen zugeordnet, sodass die Nutzung nachvollziehbar und prüfbar bleibt.