Manche Aktionen brauchen mehr als einen gültigen API-Token. Dieser Beitrag zeigt Schritt für Schritt, wie du für eine kritische Aktion ein Bestätigungstoken erzeugst und einlöst. Als Beispiel dient die Neuinstallation eines Servers.

  • Warum manche Aktionen zusätzlich bestätigt werden
  • Token per Webinterface oder API erzeugen
  • Token im X-Confirmation-Token-Header einlösen

Wann brauche ich ein Bestätigungstoken?

Kritische Aktionen mit Daten-, Kosten- oder Verfügbarkeitsfolgen verlangen zusätzlich zum API-Token ein Bestätigungstoken. Dazu gehören unter anderem: Backup oder Snapshot zurückspielen, Betriebssystem neu installieren, Serverausstattung ändern, Rescue-Modus aktivieren, ISO einbinden, neuen Server bestellen und ein Hosting sofort kündigen.

Warum das so gebaut ist, steht in Wie ist die API abgesichert?. Kurz gesagt: Selbst ein Token mit vollen Schreibrechten kann eine solche Aktion nicht in einem einzigen Schritt auslösen. Es braucht immer eine bewusste, zweite Bestätigung.

Der Ablauf in drei Schritten

  1. Du rufst die kritische Route auf. Ohne Bestätigungstoken lehnt die API ab und sagt dir, welches Token sie erwartet.
  2. Du erzeugst das passende Bestätigungstoken, im Webinterface oder per API.
  3. Du wiederholst den Aufruf und sendest das Token mit. Erst jetzt wird die Aktion ausgeführt.

Schritt 1: Aktion aufrufen, ohne Token

Du rufst die Neuinstallation auf, wie du es normal tun würdest.

curl --request POST \
  --url https://api.pph.systems/api/vps/10001/rebuild \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer sk_live_XXXX' \
  --data '{ "osid": "latest" }'

Die API führt nichts aus. Sie antwortet mit HTTP 400 und erklärt, was fehlt:

{
  "error": true,
  "type": "confirmation_error",
  "message": "Confirmation token not found by value.",
  "required_type": "reinstall_os",
  "required_id": "10001",
  "hint_route": "https://api.pph.systems/api/confirmation-token?for=reinstall_os&related_id=10001",
  "trace_id": "00000000-0000-0000-0000-000000000000"
}

Die Antwort ist selbsterklärend. required_type nennt die Art der Bestätigung, hier reinstall_os. required_id nennt die Ressource, hier den Server mit der ID 10001. hint_route liefert dir die fertige Adresse, unter der du das passende Token erzeugst.

Schritt 2: Bestätigungstoken erzeugen

Du hast zwei Wege.

Über das Webinterface

  1. Öffne in deinem Kundenbereich (Vionity) den Bereich API v2 und dort Neuen Bestätigungstoken erstellen.
  2. Wähle unter Kontext die Aktion aus. Für unser Beispiel ist das die Neuinstallation.
  3. Wähle unter Zugehörige ID den betroffenen Server aus.
  4. Klick auf Erstellen. Du erhältst den Token-Wert.
Wann brauche ich ein Bestätigungstoken?

Über die API

Sende eine POST-Anfrage an die Adresse aus hint_route. Kontext und Ressource stehen als Parameter in der URL.

curl --request POST \
  --url 'https://api.pph.systems/api/confirmation-token?for=reinstall_os&related_id=10001' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer sk_live_XXXX'

Die Antwort enthält den Token-Wert, zum Beispiel:

{
  "data": {
    "token": "ct_9f2c8a1b...",
    "for": "reinstall_os",
    "related_id": 10001,
    "expires_at": "2026-08-21T07:15:00.000000Z"
  }
}

Je nach Aktion kann das Erzeugen weitere Pflichtparameter verlangen. Die genaue Vorgabe zeigt dir die API-Dokumentation der jeweiligen Route.

Schritt 3: Token einlösen

Jetzt wiederholst du den Aufruf aus Schritt 1 und hängst den Token-Wert in den Header X-Confirmation-Token.

curl --request POST \
  --url https://api.pph.systems/api/vps/10001/rebuild \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer sk_live_XXXX' \
  --header 'X-Confirmation-Token: ct_9f2c8a1b...' \
  --data '{ "osid": "latest" }'

Passt das Token zu Aktion und Ressource und ist es noch gültig, nimmt die API die Anfrage an und die Aktion startet.

Eigenschaften des Bestätigungstokens

  • Fest gebunden: Ein Token gilt nur für genau eine Aktion (for) und genau eine Ressource (related_id). Für einen anderen Server oder eine andere Aktion brauchst du ein neues Token. Für VPS Order gibst du Hosting „0“ an.
  • Einmalig: Nach dem Einlösen ist der Token verbraucht.
  • Zeitbegrenzt: Nach Ablauf wird der Token abgewiesen und du erzeugst einen neuen.

Diese drei Eigenschaften zusammen sorgen dafür, dass eine Bestätigung nicht versehentlich wiederverwendet oder auf eine andere Ressource umgemünzt werden kann.

Künftig kann ein automatisierter Ablauf, etwa ein KI-Assistent, dir einen vorausgefüllten Vionity-Link schicken, statt das Token selbst zu erzeugen. Du öffnest den Link, das Formular ist bereits mit Kontext und zugehöriger Ressource befüllt, und du erhältst ein zeitbegrenztes Einmaltoken für genau diese Aktion. Dieses Token trägst du dann als X-Confirmation-Token in den Aufruf ein.

Der Vorteil: Die eigentliche Freigabe passiert bei dir im Browser, nicht im automatisierten Client. So bleibt die Kontrolle über kritische Aktionen bei dir, selbst wenn der Client vollautomatisch läuft.

Wie geht es weiter?

Noch Fragen?

Technische Fragen zur API beantworten dir unsere Entwickler direkt in unserem Discord. Stell deine Frage im Entwickler-Channel und pinge das Dev-Team an.