Authentifizierung

Programme authentifizieren sich mit API-Schlüsseln. Ein Schlüssel handelt als das Mitglied, das ihn erstellt hat, beschränkt auf die Berechtigungen, die Sie dem Schlüssel geben. Es gibt keinen Token-Austausch: Der Schlüssel selbst ist die Zugangsdaten, die bei jedem Aufruf gesendet werden.

API-Schlüssel werden von Administratoren unter API Keys verwaltet (im Bereich Developer des Menüs). Zum Erstellen von Schlüsseln wird ein Tarif mit API-Schlüsseln benötigt.

Schlüssel erstellen

1. Öffnen Sie API Keys und wählen Sie New API Key.
2. Geben Sie einen Name ein (bis zu 100 Zeichen) und optional eine Description (bis zu 500 Zeichen).
3. Wählen Sie unter Module permissions aus, was der Schlüssel darf, jeweils ein Modul nach dem anderen. Jedes Modul bietet eine Voreinstellung Read only; Sie können auch einzelne Berechtigungen ankreuzen. Mit Search modules or permissions… finden Sie ein Modul oder eine Berechtigung. Die Auswahl zeigt nur Berechtigungen, die Sie selbst besitzen: „Der Schlüssel kann höchstens das, was Sie selbst dürfen. Wenn Ihre eigenen Rechte später eingeschränkt werden, verliert der Schlüssel sie ebenfalls.“
4. Legen Sie Expires on fest. Standardmäßig sind es 90 Tage ab heute, höchstens ein Jahr („90 Tage standardmäßig, höchstens ein Jahr.“).
5. Füllen Sie optional IP allowlist aus: ein Subnetz pro Zeile, zum Beispiel 10.0.0.0/8 oder 203.0.113.7/32. Leer bedeutet jede Adresse, die Ihre Organisation erlaubt.
6. Lassen Sie Integration scopes (advanced) leer, es sei denn, die eigene Dokumentation einer Integration verlangt einen Wert (zum Beispiel SCIM-Provisioning).
7. Wählen Sie Create Key und kopieren Sie den Schlüssel sofort.

Wenn Sie Zwei-Faktor-Authentifizierung oder einen Passkey haben, bittet Hermetry Sie, dies zu bestätigen, bevor der Schlüssel erstellt wird. Ein Schlüssel kann nicht erstellt werden, während Sie ein Mitglied impersonieren.

Schlüsselformat

sk_live_<first 8 characters of the organisation id>_<48 random hexadecimal characters>

live-Schlüssel gehören zum Produktivdienst, test-Schlüssel zu Testinstallationen, damit die beiden nicht verwechselt werden können.

Schlüssel verwenden

Senden Sie den Schlüssel bei jedem Aufruf im Header Authorization:

curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
  -H "Authorization: Bearer sk_live_…"

• Eine Anfrage mit einem API-Schlüssel wird nur als dieser Schlüssel geprüft. Ein Browser-Cookie in derselben Anfrage wird ignoriert.
• Schlüssel funktionieren nur auf den Pfaden Ihrer Organisation (/tenant/<tenantId>/api/...). Die Organisation des Schlüssels muss mit der tenantId im Pfad übereinstimmen.
• Ein Schlüssel funktioniert nie auf Plattform-, Konto- oder Anmelderouten.

Was ein Schlüssel darf

Bei jedem Aufruf müssen alle folgenden Bedingungen erfüllt sein:

1. Der Schlüssel besitzt die Berechtigung, die die Route benötigt.
2. Das Modul der Berechtigung ist für Ihre Organisation aktiviert.
3. Das Mitglied, das den Schlüssel erstellt hat, besitzt die Berechtigung jetzt: Maßgeblich sind seine Rolle, seine Gruppen und Ihre Zugriffsrichtlinien.
4. Das Mitglied ist weiterhin aktives Mitglied und die Organisation ist aktiv.

Ein Schlüssel handelt mit höchstens der Rolle Admin, auch wenn ein Owner ihn erstellt hat. Daher kann ein Schlüssel nie Owner-only-Berechtigungen besitzen (zum Beispiel rohe Gerätebefehle, Firmware-Signierschlüssel, gefährliche Geräteeinstellungen, Rotation eines Webhook-Secrets) und nie Berechtigungen der Identitäts- und Zugriffsmodule (Anmeldung, Konten, API-Schlüssel, Mitglieder, Sitzungen). Ein Schlüssel kann daher keine Schlüssel erstellen oder rotieren.

Service-Schlüssel

Ein Schlüssel hört normalerweise auf zu funktionieren, wenn sein Ersteller die Organisation verlässt. Ein Owner kann den Schlüssel öffnen und Mark as service key auswählen: Er funktioniert dann weiter, nachdem sein Ersteller gegangen ist („Ja: überdauert seinen Ersteller“) und handelt als der Owner, der ihn markiert hat.

Erlaubte Netzwerke

Die IP-Allowlist eines Schlüssels enthält bis zu 100 Subnetze in CIDR-Form; eine einzelne Adresse ist /32. Aufrufe von anderswo werden mit 403 abgelehnt: „Dieser API-Schlüssel darf von der aktuellen IP-Adresse aus nicht verwendet werden.“ Ein Schlüssel ohne eigene Liste verwendet die Standardliste der Organisation (siehe Settings unten). Die eigenen IP-Allow- und Deny-Listen Ihrer Organisation für die Anmeldung gelten auch für Schlüssel.

Ablauf

Jeder Schlüssel läuft ab. Standard sind 90 Tage; das späteste Datum liegt 365 Tage in der Zukunft, oder früher, wenn Ihre Organisation ein niedrigeres Maximum festlegt. Abgelaufene Schlüssel stoppen von selbst. Ein Administrator kann außerdem abgelaufene Schlüssel bereinigen (POST /api/api-keys/sweep-expired), um sie als inaktiv zu markieren und pro Schlüssel ein Webhook-Ereignis api_key.expired zu senden.

Rotieren, deaktivieren und widerrufen

Öffnen Sie einen Schlüssel, um seine Identity, Usage (zuletzt verwendet, zuletzt verwendete IP, Prüfungen insgesamt), Module permissions und Rotation history zu sehen.

• Rotate key erstellt einen Nachfolger mit denselben Berechtigungen, Scopes, Netzwerklisten und derselben Umgebung. Legen Sie das Grace window (days) fest: Der alte Schlüssel funktioniert bis zu dessen Ende weiter. „0 widerruft den alten Schlüssel sofort.“ Kopieren Sie das neue Secret sofort.
• Deactivate stoppt einen Schlüssel, bis Sie ihn wieder mit Activate aktivieren. Ein rotierter Schlüssel kann nicht reaktiviert werden: „Ein rotierter Schlüssel kann nicht reaktiviert werden; verwenden Sie seinen Nachfolger.“
• Revoke löscht den Schlüssel: „Alle Integrationen, die diesen Schlüssel verwenden, funktionieren sofort nicht mehr. Diese Aktion kann nicht rückgängig gemacht werden.“
• Edit ändert die Modulberechtigungen des Schlüssels. Sie können jede Berechtigung entfernen und nur Berechtigungen hinzufügen, die Sie selbst besitzen. Integrations-Scopes können nur eingeengt werden.

Bei einem Vorfall kann ein Administrator alle aktiven Schlüssel der Organisation in einem Schritt widerrufen.

{
    "graceSeconds": 86400
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/{apiKeyId}/rotate' \
  -H 'Content-Type: application/json' \
  -d '{"graceSeconds":86400}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Only an active, unexpired key that has not been rotated yet can be rotated.",
    "code": "CONFLICT"
}

Schlüssel per HTTP verwalten

Schlüssel werden von einem angemeldeten Administrator verwaltet. Ein API-Schlüssel kann keine Schlüssel erstellen, ändern oder rotieren.

{
    "name": "Plant ERP",
    "permissions": [
        "iot_device.devices.read",
        "telemetry.read"
    ],
    "ipAllowlist": [
        "203.0.113.0/24"
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Plant ERP","permissions":["iot_device.devices.read","telemetry.read"],"ipAllowlist":["203.0.113.0/24"]}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Select at least one module permission or integration scope."
}

{
    "message": "An API key can only receive permissions you hold yourself."
}

{
    "message": "The expiry date must be in the future."
}

Schlüssel prüfen

{
    "scope": "read"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/verify' \
  -H 'Content-Type: application/json' \
  -d '{"scope":"read"}'

{
    "valid": true,
    "key": {
        "name": "Plant ERP",
        "…": "…"
    }
}

{
    "valid": false,
    "message": "scope must be a string"
}

{
    "valid": false,
    "message": "Invalid or expired API key."
}

{
    "valid": false,
    "message": "Too many requests."
}

Einstellungen

Administratoren legen die Schlüsselrichtlinie der Organisation unter API Keys > Einstellungen (Zahnrad-Schaltfläche) fest:

Die übrigen für Schlüssel geltenden Limits finden Sie unter Fehler und Rate Limits.

Schlüssel überwachen

• Für jeden Schlüssel wird gespeichert, wann und von welcher Adresse er zuletzt verwendet wurde.
• Ein Schlüssel, der 14 Tage lang nicht verwendet und dann von einer neuen Adresse aus genutzt wird, löst ein Audit-Ereignis aus („A dormant API key was used from a new address“), höchstens einmal pro Schlüssel und Adresse pro Stunde.
• Jeder abgelehnte Schlüsselaufruf wird im Audit-Log protokolliert.
• Webhooks können Sie über Schlüssel informieren: api_key.created, api_key.updated, api_key.rotated, api_key.deleted, api_key.expired.

Eine Checkliste finden Sie unter API-Key-Härtung.