API-Tokens

API-Tokens ermöglichen Ihren externen Systemen und Skripten einen sicheren, eingeschränkten Zugriff auf die Mirox-Plattform, ohne dass Sie Ihre Anmeldedaten weitergeben müssen. Sie erstellen sie in Ihrem Profil, weisen jedem Token nur die benötigten Berechtigungen zu und können jedes davon jederzeit widerrufen oder rotieren.

Überblick

Anders als Ihr Benutzername und Passwort hat ein API-Token:

Eine bestimmte Berechtigungsgruppe, die einschränkt, worauf es zugreifen kann
Ein konfigurierbares Ablaufdatum (Standard ein Jahr, maximal fünf Jahre)
Die Möglichkeit, einzeln auf ein neues Geheimnis rotiert oder widerrufen zu werden, ohne Ihr Konto oder Ihre anderen Tokens zu berühren
Eine eigene Nutzungshistorie (Zeitpunkt der letzten Verwendung, Quell-IP, Standort, Browser und Betriebssystem), sodass Sie nachvollziehen können, wie sich jede Integration verhält

Sie können gleichzeitig bis zu 64 Tokens halten.

API-Tokens erstellen

API-Tokens können über die Mirox-Weboberfläche erstellt werden:

Melden Sie sich bei Ihrem Mirox-Konto an
Öffnen Sie das Profilmenü (oben rechts) und wählen Sie Profil
Wählen Sie den Tab „API-Tokens“
Klicken Sie auf „Neues Token erstellen“
Konfigurieren Sie die Token-Einstellungen:
- Name (beschreibende Bezeichnung für das Token)
- Ablaufdatum (Standard 1 Jahr, falls nicht angegeben, maximal 5 Jahre)
- Berechtigungsumfang (bestimmte Ressourcen und Aktionen, auf die das Token zugreifen kann)
Klicken Sie auf „Token generieren“

In Mirox öffnen: Profil ▸ API-Tokens — verwalten Sie Ihre Tokens über das Profilmenü ▸ Profil und anschließend den Tab „API-Tokens“.

Speichern Sie Ihr Token sofort

Kopieren Sie das Token und bewahren Sie es sicher auf – es wird nur einmal angezeigt. Wenn Sie das Token verlieren, müssen Sie es rotieren oder ein neues erstellen.

Tokens werden aus einer Browser-Sitzung erstellt

Das Erstellen und Rotieren von Tokens erfordert eine aktive, angemeldete Web-Sitzung. Ein Token kann nicht verwendet werden, um andere Tokens zu erzeugen oder zu rotieren, sodass ein vorhandenes API-Token allein Ihren Token-Bestand nicht verwalten kann.

Best Practices für die Token-Sicherheit

Beim Arbeiten mit API-Tokens:

Sicher speichern – Behandeln Sie Tokens wie Passwörter; codieren Sie sie niemals fest in Anwendungen ein
Umgebungsvariablen verwenden – Speichern Sie Tokens in Umgebungsvariablen oder sicheren Anmeldedatenspeichern
Umfang begrenzen – Erstellen Sie Tokens mit den minimal erforderlichen Berechtigungen für die Integration
Angemessene Ablaufdaten festlegen – Verwenden Sie kürzere Ablaufzeiträume für temporäre Integrationen
Rotation einplanen – Setzen Sie sich Kalendererinnerungen vor dem Ablauf des Tokens, um die Dienstkontinuität sicherzustellen
Regelmäßig rotieren – Nutzen Sie die integrierte Rotieren-Aktion, um das Geheimnis eines Tokens regelmäßig vor seinem Ablauf zu erneuern, insbesondere bei Produktivsystemen
Nicht genutzte widerrufen – Widerrufen Sie nicht mehr benötigte Tokens sofort
Nutzung überwachen – Prüfen Sie die Token-Aktivität regelmäßig über die Mirox-Oberfläche

Warnung

Tokens laufen zum konfigurierten Datum ab, und alle Integrationen, die dieses Token verwenden, hören sofort auf zu funktionieren.

API-Tokens verwenden

API-Tokens werden in HTTP-Anfragen als Bearer-Token im Authorization-Header verwendet:

Authorization: Bearer your-api-token

Die folgenden Beispiele erfordern ein Token in der Berechtigungsgruppe Full Access.

Beispiel für eine HTTP-Anfrage

GET /api/v1/park HTTP/1.1
Host: service.mirox.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Curl-Beispiel

curl -X GET \
  https://service.mirox.io/api/v1/park \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

Token-Berechtigungen

API-Tokens unterliegen der API-Token-Berechtigungsebene der Mirox-Plattform. Wichtige Punkte zu den Token-Berechtigungen:

Tokens erben die Berechtigungen des Benutzers, der sie erstellt hat (niemals mehr)
Berechtigungen können auf Funktionsebene weiter eingeschränkt werden
Tokens arbeiten innerhalb desselben hierarchischen Berechtigungsmodells wie Benutzerkonten
Alle Sicherheitskontrollen der Plattform gelten auch für den tokenbasierten Zugriff

Ausführliche Informationen dazu, wie API-Tokens in die Gesamtarchitektur der Berechtigungen passen, finden Sie in der Dokumentation zum Berechtigungssystem.

Berechtigungsgruppen

Wenn Sie ein Token erstellen, wählen Sie eine von drei Berechtigungsgruppen, die festlegt, worauf es zugreifen kann:

Full Access – gewährt dem Token dieselben Berechtigungen wie Ihrem Benutzerkonto, innerhalb Ihres Umfangs. Jeder Dienst, der es verwendet, kann plattformweit in Ihrem Namen handeln, wählen Sie diese Option daher nur, wenn eine Integration wirklich breiten Zugriff benötigt.
Reporting – beschränkt das Token auf Reporting-Funktionen: das Erstellen von Berichten und das Exportieren von Daten.
Timeseries Database – beschränkt das Token auf Endpunkte zur Abfrage von Zeitreihen, um Messdaten programmatisch abzurufen (zum Beispiel mit MiroxQL).

Wählen Sie die engste Gruppe, die Ihre Integration abdeckt. Ein Reporting- oder Timeseries-Database-Token kann nichts außerhalb seines Umfangs erreichen, was den Schadensradius begrenzt, falls es jemals kompromittiert wird.

Verwaltung des Token-Lebenszyklus

Token-Nutzung überwachen

Verfolgen Sie die Aktivität von API-Tokens über:

Den Abschnitt „API-Tokens“ in Ihrem Profil
Audit-Logs, die zeigen, wann und wie jedes Token verwendet wurde

Tokens rotieren

Die Rotation ersetzt das Geheimnis eines Tokens, ohne dessen Namen, Berechtigungsgruppe oder Platz in Ihrer Token-Liste zu ändern. So können Sie einen Schlüssel planmäßig erneuern oder auf einen vermuteten Leak reagieren, während derselbe Token-Eintrag in der Konfiguration Ihrer Integrationen erhalten bleibt.

So rotieren Sie ein Token:

Navigieren Sie zum Abschnitt „API-Tokens“ in Ihrem Profil
Suchen Sie das Token in der Liste und wählen Sie „Rotieren“
Kopieren Sie das neue Geheimnis sofort – es wird nur einmal angezeigt
Aktualisieren Sie das Geheimnis in der Integration, die es verwendet

Die Rotation stellt ein neues Geheimnis aus, setzt das Ablauffenster zurück und löscht die aufgezeichnete Nutzungshistorie des Tokens. Das alte Geheimnis funktioniert sofort nicht mehr, aktualisieren Sie daher Ihre Integrationen als Teil der Rotation.

Planen Sie die Rotation in Wartungsfenster ein

Da das vorherige Geheimnis im Moment der Rotation ungültig wird, beginnt jede Integration, die noch den alten Wert verwendet, zu scheitern. Rotieren Sie während eines Wartungsfensters oder seien Sie bereit, das nutzende System sofort zu aktualisieren.

Tokens widerrufen

So widerrufen Sie ein Token:

Navigieren Sie zum Abschnitt „API-Tokens“ in Ihrem Profil
Suchen Sie das Token in der Liste
Klicken Sie auf „Widerrufen“
Bestätigen Sie die Aktion

Der Widerruf wird sofort wirksam, und alle nachfolgenden Anfragen, die das Token verwenden, schlagen fehl.

Nutzungsbeschränkungen

API-Tokens unterliegen denselben Rate-Limits wie normale Benutzerkonten. Einzelheiten zu diesen Beschränkungen finden Sie im Abschnitt zur Ratenbegrenzung in der Dokumentation zu den Authentifizierungskonzepten.

Fehlerbehebung

Häufige Token-Probleme und Lösungen:

Problem	Mögliche Ursache	Lösung
401 Unauthorized	Ungültiges, widerrufenes, rotiertes oder abgelaufenes Token	Prüfen Sie die Gültigkeit des Tokens, oder rotieren Sie es / erstellen Sie ein neues
403 Forbidden	Die Berechtigungsgruppe des Tokens deckt den angeforderten Endpunkt nicht ab	Verwenden Sie ein Token in einer Berechtigungsgruppe, die den Zugriff gewährt, oder eines in Full Access
429 Too Many Requests	Rate-Limit überschritten	Verlangsamen Sie die Anfragen und implementieren Sie eine Strategie mit exponentiellem Backoff

Code-Beispiele

Funktionierenden Code, der ein API-Token von Anfang bis Ende verwendet, finden Sie hier:

Externer Berichtsgenerator – ein Python-Skript, das sich mit einem Token authentifiziert und einen Metrik-Export abruft
MiroxQL – die Abfragesprache zum Abrufen von Zeitreihendaten mit einem Timeseries-Database-Token

Tips

Genaue Endpunkte und Parameter können sich im Laufe der Zeit ändern. Die maßgebliche Live-Referenz ist immer die OpenAPI-Dokumentation unter /docs.