API

Alles, was das Dashboard zeigt, auch als JSON – mit eigenen Schlüsseln und Rechten.

Die API liefert dieselben Daten wie das Dashboard. Sie ist gedacht für eigene Auswertungen, Statusseiten, Automatisierung und Anbindung an vorhandene Werkzeuge.

Anmeldung #

Erzeuge einen Schlüssel unter Einstellungen → API. Übergib ihn als Bearer-Token:

curl -H "Authorization: Bearer n64_dein_schluessel" \
     https://app.node64.de/api/v1/me

Der Schlüssel wird einmal angezeigt. Wir speichern nur seinen Hash.

Rechte #

Jeder Schlüssel bekommt genau die Rechte, die du auswählst:

Recht	Erlaubt
`account:read`	Konto- und Nutzerdaten lesen
`devices:read`	Geräte, Gruppen und Uploads lesen
`devices:write`	Geräte bearbeiten, Gruppen anlegen, Geräte löschen
`findings:read`	Befunde lesen
`alerts:read`	Alarme und Regeln lesen

Ein Schlüssel für eine Statusseite braucht findings:read – mehr nicht.

Endpunkte #

Methode	Pfad	Zweck
`GET`	`/api/v1/me`	Konto, Nutzer, Tarif
`GET`	`/api/v1/devices`	alle Geräte
`GET`	`/api/v1/devices/{id}`	ein Gerät mit Details
`PATCH`	`/api/v1/devices/{id}`	Gerät ändern (Name, Gruppe, Rolle)
`DELETE`	`/api/v1/devices/{id}`	Gerät entfernen
`GET`	`/api/v1/groups`	Gerätegruppen
`POST`	`/api/v1/groups`	Gruppe anlegen
`GET`	`/api/v1/findings`	Befunde, filterbar
`GET`	`/api/v1/uploads`	Upload-Historie
`GET`	`/api/v1/alerts`	ausgelöste Alarme
`GET`	`/api/v1/openapi.json`	die Spezifikation

Beispiele #

Alle offenen Befunde ab „hoch":

curl -H "Authorization: Bearer $KEY" \
     "https://app.node64.de/api/v1/findings?severity=high&status=open"

Wann jedes Gerät zuletzt gemeldet hat:

curl -s -H "Authorization: Bearer $KEY" \
     https://app.node64.de/api/v1/devices | jq '.data[] | {name, last_seen_at, agent_version}'

Einen Score gibt es nicht – auch nicht in der API. Warum, steht unter Befunde verstehen.

Antwortformat #

{
  "data": [ ... ],
  "meta": { "count": 12 }
}

Fehler kommen mit passendem Statuscode und einem Körper:

{ "error": "forbidden", "message": "Missing scope: findings:read" }

Grenzen #

Nur lesen und verwalten, nicht steuern. Es gibt keinen Endpunkt, der etwas auf einem Gerät ausführt – aus demselben Grund, aus dem der Agent keinen Kommandokanal hat.
Rate-Limit je Schlüssel. Wer in eine Grenze läuft, bekommt 429 und wartet kurz.
Versioniert. /api/v1/ bleibt stabil; Änderungen, die etwas brechen, bekommen /api/v2/.

OpenAPI #

Die vollständige Spezifikation liegt unter /api/v1/openapi.json und lässt sich in jeden API-Client importieren.