Die Management-API
Alles, was Sie pro App im Konsolen-Panel tun, geht auch als REST-Aufruf, sodass eine Flotte aus CI/CD, Konfigurationsverwaltung oder einem MDM bereitgestellt werden kann. Diese Seite ist die Endpunkt-Referenz: was jeder Aufruf tut, wie Sie sich authentifizieren und warum die API nie geschützten Inhalt sieht.
Worum es geht
- Eine kleine REST-Fläche für den App-Lebenszyklus: Apps anlegen, enrollen, auflisten, deaktivieren und löschen.
- Für Automatisierung gebaut: Backen Sie einen nicht-enrollten Daemon in ein Golden Image und prägen Sie Enrollment-Codes im Voraus; jede Maschine enrollt sich beim ersten Start selbst.
- Maschinenlesbar: Eine OpenAPI-3-Spezifikation wird neben dieser Seite veröffentlicht.
Management-Ebene gegen Daten-Ebene
Die entscheidende Eigenschaft ist, was diese API nicht sieht. Das System hat zwei getrennte Ebenen:
| Ebene | Verkehr | Sieht Inhalt? |
|---|---|---|
| Management-Ebene | Diese API: nur App-Lebenszyklus und Metadaten (Kennung, Name, Status, Plattform, Agent-Version, Zeitstempel, Enrollment-Codes). | Nein: kein Memory-Inhalt, kein Diff, keine Bewertungsnutzlast quert sie je. |
| Daten-Ebene | Der eigene Verkehr des Daemon: Check-ins und, im cloud-gestützten Fluss, die Bewertung redigierter Diffs. | Inhalt bleibt auf dem Gerät; nur eine redigierte Projektion wird bewertet. |
Authentifizierung
Aufrufer authentifizieren sich mit einem Bearer-Schlüssel, der im Panel unter Einstellungen, API-Schlüssel erstellt wird. Der Schlüssel (pz_live_ gefolgt von vierzig Zeichen) wird einmal angezeigt; at-rest wird nur sein SHA-256-Hash gespeichert, sodass eine Datenbank-Offenlegung keine nutzbare Zugangskennung ergibt.
curl -H "Authorization: Bearer pz_live_..." \ https://poisonzero.com/api/v1/apps
- Eigentümergebunden: Jede Anfrage ist an den Eigentümer des Schlüssels gebunden.
- Keine Aufzählung: Eine fremde oder unbekannte App antwortet mit identischem
404, sodass Kennungen ausserhalb Ihrer Flotte nicht abgetastet werden können. - Zehn aktive Schlüssel pro Konto; jeder Schlüssel kann einzeln widerrufen werden.
Endpunkte
Die Endpunkte spiegeln das Panel und werden über HTTPS unter poisonzero.com/api/v1/ erreicht. Jeder Aufruf nimmt den Bearer-Schlüssel:
| Endpunkt | Zweck | Liefert |
|---|---|---|
POST /v1/apps | Legt eine App und einen ersten Enrollment-Code in einem Aufruf an (optionaler Body {"name":"..."}). | 201 mit appId, enrollCode, enrollCodeExpiresAt. |
GET /v1/apps | Listet Ihre Flotte. | Ein Eintrag pro App (siehe App-Objekt unten). |
GET /v1/apps/{appId} | Ruft eine App ab. | 404 für unbekannte oder fremde IDs. |
POST /v1/apps/{appId}/enroll-code | Prägt einen frischen Enrollment-Code, etwa um eine Maschine neu bereitzustellen. | 201; Codes sind einmalig und 30 Tage gültig. |
POST /v1/apps/{appId}/revoke | Deaktiviert eine App; Status wird revoked und die Zugangskennung des Daemon wirkt sofort nicht mehr. | appId und status. |
DELETE /v1/apps/{appId} | Löscht eine App dauerhaft (App, Konfiguration, Daemon-Identität, offene Codes, Einträge der Prüfwarteschlange; Audit-Logs bleiben erhalten). | 204. |
GET / PUT / DELETE /v1/otel-config | Verwaltet die OpenTelemetry-Export-Konfiguration der Flotte (Enterprise). | Siehe die Observability-Export-Seite. |
GET und PUT auf /v1/otel-config setzen einen Enterprise-Eigentümer voraus (sonst 403); DELETE ist immer erlaubt, damit ein herabgestufter Eigentümer ein gespeichertes Collector-Geheimnis noch entfernen kann. Der Export selbst: OpenTelemetry-Export.Das App-Objekt
Auflisten und Abrufen liefern die Lebenszyklus-Metadaten jeder App, nie Inhalt:
| Feld | Bedeutung |
|---|---|
appId | Stabile App-Kennung. |
name | Anzeigename. |
status | pending, active oder revoked. |
platform | Gemeldetes Betriebssystem. |
agentVersion | Gemeldete Daemon-Version. |
lastSeenAt, createdAt | Zeitstempel. |
Transport
- HTTPS unter
poisonzero.com/api/v1/; ein Reverse-Proxy leitet nur Methode, Pfad, Authorization-Header, Content-Type und einen größenbegrenzten Body weiter. - Der Pfad wird bis zum Fixpunkt dekodiert, und jedes Punkt-Segment oder jeder Backslash wird abgewiesen, was Path-Traversal-Versuche schließt.
- Die Flottenverwaltung ist nicht an ein aktives Abonnement gekoppelt, sodass Sie bereitstellen und widerrufen können, während ein Plan noch arrangiert wird.
Fehler
Alle Fehler teilen eine Form, {"error":{"code":"...","message":"..."}}, mit einem stabilen maschinenlesbaren Code:
| Status | Bedeutung |
|---|---|
400 | Validierung, etwa invalid_name oder limit_reached. |
401 | Fehlender, ungültiger oder widerrufener Schlüssel, oder ein deaktiviertes Konto. |
404 | Unbekannter Endpunkt, oder eine unbekannte oder fremde App-ID. |
413 | Anfrage-Body über 64 KiB (payload_too_large). |
429 | Zu viele Anfragen; verlangsamen und erneut versuchen (bis zu 600 pro Minute pro Konto). |
/docs/api/openapi.json veröffentlicht.Weiterlesen
Der über /v1/otel-config konfigurierte Enterprise-Export: OpenTelemetry-Export. Wo Enrollment-Codes beim Rollout genutzt werden: PoisonZero installieren.
Stellen Sie Ihre ganze Flotte per Skript bereit.
Anlegen, enrollen und widerrufen über REST, mit einem statischen API-Schlüssel. Die API sieht nie geschützten Inhalt.
Sign me up