{"data":{"external_id":3567,"slug":"kritische-aktionen-mit-einem-bestaetigungstoken-freigeben","title":"Kritische Aktionen mit einem Best\u00e4tigungstoken freigeben","content":"Manche Aktionen brauchen mehr als einen g\u00fcltigen API-Token. Dieser Beitrag zeigt Schritt f\u00fcr Schritt, wie du f\u00fcr eine kritische Aktion ein Best\u00e4tigungstoken erzeugst und einl\u00f6st. Als Beispiel dient die Neuinstallation eines Servers.\nWarum manche Aktionen zus\u00e4tzlich best\u00e4tigt werden\nToken per Webinterface oder API erzeugen\nToken im X-Confirmation-Token-Header einl\u00f6sen\nWann brauche ich ein Best\u00e4tigungstoken?\nKritische Aktionen mit Daten-, Kosten- oder Verf\u00fcgbarkeitsfolgen verlangen zus\u00e4tzlich zum API-Token ein Best\u00e4tigungstoken. Dazu geh\u00f6ren unter anderem: Backup oder Snapshot zur\u00fcckspielen, Betriebssystem neu installieren, Serverausstattung \u00e4ndern, Rescue-Modus aktivieren, ISO einbinden, neuen Server bestellen und ein Hosting sofort k\u00fcndigen.\nWarum 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\u00f6sen. Es braucht immer eine bewusste, zweite Best\u00e4tigung.\nDer Ablauf in drei Schritten\nDu rufst die kritische Route auf. Ohne Best\u00e4tigungstoken lehnt die API ab und sagt dir, welches Token sie erwartet.\nDu erzeugst das passende Best\u00e4tigungstoken, im Webinterface oder per API.\nDu wiederholst den Aufruf und sendest das Token mit. Erst jetzt wird die Aktion ausgef\u00fchrt.\nSchritt 1: Aktion aufrufen, ohne Token\nDu rufst die Neuinstallation auf, wie du es normal tun w\u00fcrdest.\ncurl --request POST \\\n  --url https:\/\/api.pph.systems\/api\/vps\/10001\/rebuild \\\n  --header 'Accept: application\/json' \\\n  --header 'Authorization: Bearer sk_live_XXXX' \\\n  --data '{ \"osid\": \"latest\" }'\nDie API f\u00fchrt nichts aus. Sie antwortet mit HTTP 400 und erkl\u00e4rt, was fehlt:\n{\n  \"error\": true,\n  \"type\": \"confirmation_error\",\n  \"message\": \"Confirmation token not found by value.\",\n  \"required_type\": \"reinstall_os\",\n  \"required_id\": \"10001\",\n  \"hint_route\": \"https:\/\/api.pph.systems\/api\/confirmation-token?for=reinstall_os&related_id=10001\",\n  \"trace_id\": \"00000000-0000-0000-0000-000000000000\"\n}\nDie Antwort ist selbsterkl\u00e4rend. required_type nennt die Art der Best\u00e4tigung, 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.\nSchritt 2: Best\u00e4tigungstoken erzeugen\nDu hast zwei Wege.\n\u00dcber das Webinterface\n\u00d6ffne in deinem Kundenbereich (Vionity) den Bereich API v2 und dort Neuen Best\u00e4tigungstoken erstellen.\nW\u00e4hle unter Kontext die Aktion aus. F\u00fcr unser Beispiel ist das die Neuinstallation.\nW\u00e4hle unter Zugeh\u00f6rige ID den betroffenen Server aus.\nKlick auf Erstellen. Du erh\u00e4ltst den Token-Wert.\n\u00dcber die API\nSende eine POST-Anfrage an die Adresse aus hint_route. Kontext und Ressource stehen als Parameter in der URL.\ncurl --request POST \\\n  --url 'https:\/\/api.pph.systems\/api\/confirmation-token?for=reinstall_os&related_id=10001' \\\n  --header 'Accept: application\/json' \\\n  --header 'Authorization: Bearer sk_live_XXXX'\nDie Antwort enth\u00e4lt den Token-Wert, zum Beispiel:\n{\n  \"data\": {\n    \"token\": \"ct_9f2c8a1b...\",\n    \"for\": \"reinstall_os\",\n    \"related_id\": 10001,\n    \"expires_at\": \"2026-08-21T07:15:00.000000Z\"\n  }\n}\nJe nach Aktion kann das Erzeugen weitere Pflichtparameter verlangen. Die genaue Vorgabe zeigt dir die API-Dokumentation der jeweiligen Route.\nSchritt 3: Token einl\u00f6sen\nJetzt wiederholst du den Aufruf aus Schritt 1 und h\u00e4ngst den Token-Wert in den Header X-Confirmation-Token.\ncurl --request POST \\\n  --url https:\/\/api.pph.systems\/api\/vps\/10001\/rebuild \\\n  --header 'Accept: application\/json' \\\n  --header 'Authorization: Bearer sk_live_XXXX' \\\n  --header 'X-Confirmation-Token: ct_9f2c8a1b...' \\\n  --data '{ \"osid\": \"latest\" }'\nPasst das Token zu Aktion und Ressource und ist es noch g\u00fcltig, nimmt die API die Anfrage an und die Aktion startet.\nEigenschaften des Best\u00e4tigungstokens\nFest gebunden: Ein Token gilt nur f\u00fcr genau eine Aktion (for) und genau eine Ressource (related_id). F\u00fcr einen anderen Server oder eine andere Aktion brauchst du ein neues Token. F\u00fcr VPS Order gibst du Hosting „0“ an.\nEinmalig: Nach dem Einl\u00f6sen ist der Token verbraucht.\nZeitbegrenzt: Nach Ablauf wird der Token abgewiesen und du erzeugst einen neuen.\nDiese drei Eigenschaften zusammen sorgen daf\u00fcr, dass eine Best\u00e4tigung nicht versehentlich wiederverwendet oder auf eine andere Ressource umgem\u00fcnzt werden kann.\nKomfortabler per Direktlink (Coming soon)\nK\u00fcnftig kann ein automatisierter Ablauf, etwa ein KI-Assistent, dir einen vorausgef\u00fcllten Vionity-Link schicken, statt das Token selbst zu erzeugen. Du \u00f6ffnest den Link, das Formular ist bereits mit Kontext und zugeh\u00f6riger Ressource bef\u00fcllt, und du erh\u00e4ltst ein zeitbegrenztes Einmaltoken f\u00fcr genau diese Aktion. Dieses Token tr\u00e4gst du dann als X-Confirmation-Token in den Aufruf ein.\nDer Vorteil: Die eigentliche Freigabe passiert bei dir im Browser, nicht im automatisierten Client. So bleibt die Kontrolle \u00fcber kritische Aktionen bei dir, selbst wenn der Client vollautomatisch l\u00e4uft.\nWie geht es weiter?\nDas Sicherheitskonzept hinter den Best\u00e4tigungstoken steht in Wie ist die API abgesichert?.\nEinen \u00dcberblick \u00fcber alle Funktionen gibt Was kann die API eigentlich?.\nNoch Fragen?\nTechnische Fragen zur API beantworten dir unsere Entwickler direkt in unserem Discord. Stell deine Frage im Entwickler-Channel und pinge das Dev-Team an.","schema":null,"facts":[],"links":[{"type":"external","url":"https:\/\/support.prepaid-hoster.de\/faq\/de\/api\/wie-ist-die-api-abgesichert.html","data":{"title":"Not Found","meta_description":"","meta":[]}},{"type":"external","url":"https:\/\/support.prepaid-hoster.de\/faq\/de\/api\/wie-ist-die-api-abgesichert.html","data":{"title":"Not Found","meta_description":"","meta":[]}},{"type":"external","url":"https:\/\/support.prepaid-hoster.de\/faq\/de\/api\/was-kann-die-api-eigentlich.html","data":{"title":"Not Found","meta_description":"","meta":[]}}]}}